IBM DataStage Flow Designer REST API

You can use the REST protocols to incorporate IBM® DataStage® Flow Designer features in your custom application. You use the REST protocol to perform actions such as compiling jobs, running jobs, and getting job status. These REST protocols are supported beginning with InfoSphere® Information Server, version 11.7.1.0.

Namespace: /com/ibm/iis/api/dscdesignerapi/api/

Version: 1.0.0

Authentication: All of these REST APIs use basic authentication.

You can use the REST protocols to complete the following tasks:

REST API calls automatically time out after 30 minutes.

Compile jobs

compileDSJob

Compiles a parallel or sequence InfoSphere DataStage job.

REST API URL:
https://<SERVICE-TIER-HOSTNAME>:<IS-Port>/ibm/iis/api/dscdesignerapi?api=compileDSJob&jobName=<JobNam
e>&projectName=<ProjectName>&hostName=<engineHostName>&getFullOutput=<true/false>&apiVersion=<apiVer>
Parameters
Parameter Description
jobName

The name of the job that you want to compile. It must be a parallel engine or sequence job.

jobName=DSJOB1
projectName

The name of the project that contains the job that you want to compile.

projectName=DSTAGE1
hostName

The host name of the computer where the engine tier is installed. 

hostName=dstage1.ibm.com
getFullOutput Optional

Specify this parameter if you want to include all output after the job is compiled. The output includes generated .osh files, job parameter details, and so on. The default value of this parameter is false. 

getFullOutput=true
apiVersion Optional

The version of the API. The default value of this parameter is LATEST. 

apiVersion=3.0
Return values

If the job is successfully compiled and deployed, the output is a JSON object that contains the following fields:

Field Description
jobName The name of the job.
restApiName The REST API name. For example, compileDSJob.
succeeded True
In addition, if you set the getFullOutput parameter to true, the following fields are also returned:
Field Description
result The generated osh script.
JobParamString The JSON object string that contains the job parameter details.
If the compile fails, the output is a JSON object that contains the following fields:
Field Description
jobName The name of the job.
restApiName The REST API name. For example, compileDSJob.
failureMessage The JSON array that contains failure details. For example, error message, error stage name, error link name, and so on where the compile failed.
succeeded False
Sample call
https://dstage.ibm.com:9443/ibm/iis/api/dscdesignerapi?api=compil
eDSJob&jobName=Sanity1&projectName=dstage1&hostName=dstage1.ibm.com

Run jobs

runDSJob

Runs a parallel or sequence InfoSphere DataStage job.

REST API URL:
https://<SERVICE-TIER-HOSTNAME>:<IS-Port>/ibm/iis/api/dscdesignerapi?api=runDSJob&jobName=<JobName>&
projectName=<ProjectName>&hostName=<engineHostName>&getFullOutput=<true/false>&apiVersion=<apiVer>
Parameters
Parameter Description
jobName

The name of the job that you want to run. It must be a parallel engine or sequence job.

jobName=DSJOB1
projectName

The name of the project that contains the job that you want to run.

projectName=DSTAGE1
hostName

The host name of the computer where the engine tier is installed. 

hostName=dstage1.ibm.com
getFullOutput Optional

Specify this parameter if you want to include all output after the job is run. The output includes generated .osh files, job parameter details, and so on. The default value of this parameter is false. 

getFullOutput=false
apiVersion Optional

The version of the API. The default value of this parameter is LATEST. 

apiVersion=3.0
jobParameters Optional

The job parameters for that job that you want to run. If you do not specify either jobParameters or runOptions, then the job run is initiated with the default values of job parameters and job run options.

You do not need to specify values for all of the job parameters that are specified in a job design. You can simply specify the value for the job parameter that you want to change for the job run. Then, the job run will update the specific parameter that you specified and will use the default values for all the remaining job parameters. You can specify a subset of the job parameter values by using the JSON request body. For example:
{"jobParameters":[{"name":"DB2_PASSWORD","value":"{iisenc}xR2lMbc
u9hQMgIS9NqSuOA=="}],"jobRunOptions":{"Warning":"50"}}
runOptions Optional

The job run options for that job that you want to run. If you do not specify runOptions, then the job run is initiated with the default values for the job run options.

You do not need to specify values for all of the job run options that are specified in a job design. You can simply specify the value for the run option that you want to change for the job run. Then, the job run will update the specific parameter that you specified and will use the default values for all the remaining run options. You can specify a subset of run options by using the JSON request body. For example:
{"jobParameters":[{"name":"DB2_PASSWORD","value":"{iisenc}xR2lMbc
u9hQMgIS9NqSuOA=="}],"jobRunOptions":{"Warning":"50"}}
Return values

If the job is successfully run, the output is a JSON object that contains the following fields:

Field Description
jobName The name of the job.
restApiName The REST API name. For example, runDSJob.
succeeded True
In addition, if you set the getFullOutput parameter to true, the following fields are also returned:
Field Description
JobStatus The job status of the job. For example, FOK or FWF.
result The string oshResult. If the job run initiation is successful and the job status is running or finished, the value returned for the result is true. If the job initiation fails, the result is false.
If the attempt to initiate the job run fails, the output is a JSON object that contains the following fields:
Field Description
jobName The name of the job.
restApiName The REST API name. For example, runDSJob.
failureMessage The JSON array that contains failure details. For example, error message, stack trace, and so on where the job run fails to start.
succeeded False
Sample call
https://dstage1.ibm.com:9443/ibm/iis/api/dscdesignerapi?api=runDSJ
ob&jobName=DstageJob1&projectName=Dstage1&hostName=dstage1.ibm.com

Get the status of jobs

getDSJobStatus

Gets the status of a parallel or sequence InfoSphere DataStage job run.

REST API URL:
https://<SERVICE-TIER-HOSTNAME>:<IS-Port>/ibm/iis/api/dscdesignerapi?api=getDSJobStatus&jobName=<JobNa
me>&projectName=<ProjectName>&hostName=<engineHostName>&getFullOutput=<true/false>&apiVersion=<apiVer>
Parameters
Parameter Description
jobName

The name of the job that you want to get the status of. It must be a parallel engine or sequence job.

jobName=DSJOB1
projectName

The name of the project that contains the job that you want to get the status of.

projectName=DSTAGE1
hostName

The host name of the computer where the engine tier is installed. 

hostName=server.ibm.com
getFullOutput Optional

Specify this parameter if you want to include all output after the job is run. The output includes generated .osh files, job parameter details, and so on. The default value of this parameter is false. 

getFullOutput=false
apiVersion Optional

The version of the API. The default value of this parameter is LATEST. 

apiVersion=3.0
Return values

If the job status is successfully retrieved, then the output is a JSON object that contains the following fields:

Field Description
jobStatus The status of the job.
restApiName The REST API name. For example, restGetDSJobStatus.
succeeded True
In addition, if you set the getFullOutput parameter to true, the following field is also returned:
Field Description
runResults A JSON object containing the link information, such as rows processed on each link, the source stage name of the link, and so on.
If the attempt to get the job status fails, the output is a JSON object that contains the following fields:
Field Description
jobStatus The job status.
restApiName The REST API name. For example, restGetDSJobStatus.
failureMessage An error message that includes error details, stack trace information, and so on.
succeeded False
Sample call
https://inf1.fyre.ibm.com:9446/ibm/iis/api/dscdesignerapi?api=getDSJobStatus&jobName=Job_1&projectName=dstage1&hostName=INF1.FYRE.IBM.COM

Import assets

importAssets

Imports assets from one InfoSphere DataStage project to another project. You can only import ISX or zip files.

REST API URL:
https://<SERVICE-TIER-HOSTNAME>:<IS-Port>/ibm/iis/api/dscdesignerapi?api=importAssets&userName=<user_name>&password=<password>&domain=<domain_name>
&projectName=<project_name>&replace=<yes/no>&includeDesign=<yes/no>&file=<file_path>&apiVersion=<apiVer>
Parameters
Parameter Description
engineName

The host name of the computer where the engine tier is installed. 

engineName=dstage1.ibm.com
domain The host name and port number of the InfoSphere Information Server services tier in the format <host_name>:port. For example, server.ibm.com:9446.
userName The InfoSphere Information Server user name.
password Your InfoSphere Information Server password.
projectName The InfoSphere DataStage project name. For example, dstage1.
includeDesign Optional

Specify yes or no to include the design. If you enter no, then only job executables are imported, but not job designs. If you enter yes, then both job executables and job designs are imported.
replace Optional

Specify yes or no to replace assets.
file The local path to the ISX file. This path must be passed in the form-data (the body of the post request). This parameter cannot be passed in the URL and requires a RESTAPI tool that allows for passing data through the form body. Use this parameter for local files to be uploaded. (Supported in InfoSphere Information Server, version 11.7.1.1 and later.)
remoteFilePath The path to the ISX file that is accessible from the engine tier. Use this parameter for files to be uploaded from the engine tier.
Return values

After the import completes, the output is a JSON object that contains the following fields:

Field Description
ImportStatus The status is either success or failed.
restApiName The REST API name. For example, restImportAssets.
message Description of the tasks involved in importing the file.
succeeded True or False
restAPiName The REST API name. For example, restImportAssets.
succeeded True or False
Sample call for a file on the engine tier
https://inf1.fyre.ibm.com:9446/ibm/iis/api/dscdesignerapi?api=importAssets&userName=isadmin&password=temp4now&replace=yes&includeDesign=yes&projectName=dstage1&remoteFilePath=/opt/IBM/gitDFD3/johnk/cognitive-version-control/dstage1/Jobs/job1/job1.isx&engineName=INF1.FYRE.IBM.COM
Sample call that uses curl for a file on a local machine
curl --location --request POST --insecure -u isadmin 'https://inf1.fyre.ibm.com:9446/ibm/iis/api/dscdesignerapi?api=importAssets&userName=isadmin&password=temp4now&engineName=INF1.FYRE.IBM.COM&projectName=dstage1&replace=yes&includeDesign=yes'
--form 'file=@/Users/johnh/Downloads/isadmin_20200410125129.isx'

Import a single ISX file from Source Code Management (SCM)

importJobsFromSCM

Imports a single ISX file from source code management (SCM) to any InfoSphere DataStage project.

REST API URL:
https://<SERVICE-TIER-HOSTNAME>:<IS-Port>/ibm/iis/api/dscdesignerapi?api=importJobsFromSCM&userName=<user_name>&password=<password>&domain=<domain_name>
&projectName=<project_name>&gitPath=<path_to_git_repository>&commitId=<commit_ID_number>&branchName=<name_of_git_branch>&replace=<yes/no>&includeDesign=<yes/no>&apiVersion=<apiVer>
Parameters
Parameter Description
domain The host name and port number of the InfoSphere Information Server services tier in the format <host_name>:port. For example, server.ibm.com:9446.
userName The InfoSphere Information Server user name.
password Your InfoSphere Information Server password.
projectName The InfoSphere DataStage project name. For example, dstage1.
gitPath The complete path of the InfoSphere Information Server project name from version control. For example, dstage1/Jobs/MyJob/MyJob.isx.
commitId The full SHA-1 object name (40-byte hexadecimal string), or a leading substring that is unique within the repository. For example, dae86e1950b1277e545cee180551750029cfe735 and dae86e.
branchName Optional

Enter the Git version control branch name. The default is master.
includeDesign Optional

Specify yes or no to include the design. If you enter no, then only job executables are imported, but not job designs. If you enter yes, then both job executables and job designs are imported.
replace Optional

Specify yes or no to replace assets.
Return values
After the import completes, the output is a JSON object that contains the following fields:
Field Description
ImportStatus The status is either success or failed.
restApiName The REST API name. For example, restIstoolImportExport.
message Description of the tasks involved in importing the file.
succeeded True or False
restAPiName The REST API name. For example, restImportJobsFromSCM.
succeeded True or False
Sample call
https://dstage.ibm.com:9443/ibm/iis/api/dscdesignerapi?api=importJobsFromSCM&userName=isadmin&password
=abcxyz&domain=dstage.ibm.com:9443&projectName=IISM&gitPath=dstage1/Jobs/importJob2/importJob2.isx&commitId=ea71243&replace
=yes&includeDesign=yes

Import multiple ISX files from Source Code Management (SCM)

importJobsFromSCM

Imports multiple ISX files from source code management (SCM) to any InfoSphere DataStage project.

REST API URL:
https://<SERVICE-TIER-HOSTNAME>:<IS-Port>/ibm/iis/api/dscdesignerapi?api=importJobsFromSCM&userName=<user_name>
&password=<password>&domain=<domain_name>&projectName=<project_name>&afterDate=<date>&beforeDate=<date>&commitMsgTxt=<commit_comments>
&branchName=<name_of_git_branch>&replace=<yes/no>&includeDesign=<yes/no>
Parameters
Parameter Description
domain The host name and port number of the InfoSphere Information Server services tier in the format <host_name>:port. For example, server.ibm.com:9446.
userName The InfoSphere Information Server user name.
password Your InfoSphere Information Server password.
projectName The InfoSphere DataStage project name. For example, dstage1.
afterDate Optional

Enter a date. All commits after the date you enter are included. For example, 2016-01-28T16:45:00-0700.

beforeDate Optional

Enter a date. All commits before the date you enter are included. For example, 2018-11-29T16:00:00-0700.

commitMsgTxt The starting partial text of a commit log message.
branchName Optional

Enter the Git version control branch name. The default is master.
includeDesign Optional

Specify yes or no to include the design. If you enter no, then only job executables are imported, but not job designs. If you enter yes, then both job executables and job designs are imported.
replace Optional

Specify yes or no to replace assets.
Return values

After the import completes, the output is a JSON object that contains the following fields:

Field Description
ImportStatus The status is either success or failed.
restApiName The REST API name. For example, restImportJobsFromSCM.
succeeded True or False
Sample call
https://dstage.ibm.com:9443/ibm/iis/api/dscdesignerapi?api=importJobsFromSCM&userName=isadmin&password=uOYl.4xe&
domain=dstage.ibm.com:9443&projectName=IISM&afterDate=2018-10-27T17:00:00-0700&beforeDate=2019-02-137T17:00:00-0700&
replace=yes&includeDesign=yes