RestJobsCategory

Jobs services category

The jobs services give you the capability to have all information about jobs and their status and act on them.

Getting jobs

Provides a collection of jobs by a filter, currently located a specific queue.

Request

Parameter	Value
URL	/jobs/list/{queue}?filter=
Method	GET
Path	queue parameter is mandatory and defined on which queue you are seaching the jobs. The valid values could be input, running, output, routing
Query	filter parameter is optional and conatins the filter string toaplly to get what you are searching. Default is *
Content-Type	application/json
Accept-Type	application/json
Body	none

Response

Status code	Description
200	OK - Returns a list of jobs
400	Bad Request - The queue passed as path parameter is not correct
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Getting job status

Provides the information where jobs (searched by job id or job name) is located, in which queue.

Request

Parameter	Value
URL	/jobs/status?filter=
Method	GET
Path	none
Query	filter parameter is optional and conatins the filter string toaplly to get what you are searching. Default is *
Content-Type	application/json
Accept-Type	application/json
Body	none

Response

Status code	Description
200	OK - Returns a list of jobs
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Getting a job by ID

Provides a job searched by its ID, currently located a specific queue.

Request

Parameter	Value
URL	/jobs/getOnlyById/{jobid}
Method	GET
Path	jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	application/json
Body	none

Response

Status code	Description
200	OK - Returns a job
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Getting a job by ID, on the specific queue

Provides a job searched by its ID, currently located a specific queue.

Request

Parameter	Value
URL	/jobs/getById/{queue}/{jobid}
Method	GET
Path	queue parameter is mandatory and defined on which queue you are seaching the jobs. The valid values could be input, running, output, routing jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	application/json
Body	none

Response

Status code	Description
200	OK - Returns a job
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Getting JCL types available

Provides a collection with all JCL types available and configured on JEM cluster.

Request

Parameter	Value
URL	/jobs/getJclTypes
Method	GET
Path	none
Query	none
Content-Type	application/json
Accept-Type	application/json
Body	none

Response

Status code	Description
200	OK - Returns a list of string which represent the JCL types. The JSON format is: ["type1", ... "typeN"]
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Holding a job

You can hold a job by its ID, currently located a specific queue.

Request

Parameter	Value
URL	/jobs/hold/{queue}/{jobid}
Method	PUT
Path	queue parameter is mandatory and defined on which queue you are seaching the jobs. The valid values could be input, running, output, routing jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	text/plain
Body	none

Response

Status code	Description
200	OK - Returns true if it was able to hold the job, otherwise false. The TEXT format is: "true" or "false"
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Releasing a job

You can release a job by its ID (previously put in hold), currently located a specific queue.

Request

Parameter	Value
URL	/jobs/release/{queue}/{jobid}
Method	PUT
Path	queue parameter is mandatory and defined on which queue you are seaching the jobs. The valid values could be input, running, output, routing jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	text/plain
Body	none

Response

Status code	Description
200	OK - Returns true if it was able to release the job, otherwise false. The TEXT format is: "true" or "false"
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Cancelling a job

You can cancel a job by its ID, which it's running.

Request

Parameter	Value
URL	/jobs/cancel/{jobid}/{force}
Method	PUT
Path	jobid parameter is mandatory and specified the job id to search. force is a boolean and mandatory and specified if the job must be cancelled in force mode
Query	none
Content-Type	application/json
Accept-Type	text/plain
Body	none

Response

Status code	Description
200	OK - Returns true if it was able to cancel the job, otherwise false. The TEXT format is: "true" or "false"
400	Bad Request - The job id passed as path parameters is not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Purging a job

You can purge a job by its ID, currently located a specific queue. Purging you can remove the job from queue and also its output will be removed from file system.

Request

Parameter	Value
URL	/jobs/purge/{queue}/{jobid}
Method	PUT
Path	queue parameter is mandatory and defined on which queue you are seaching the jobs. The valid values could be input, running, output, routing jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	text/plain
Body	none

Response

Status code	Description
200	OK - Returns true if it was able to purge the job, otherwise false. The TEXT format is: "true" or "false"
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Updating a job

You can update attributes a job by its ID, currently located a specific queue. not all attributes can be changed, only its affinity, domain, environment to be executed and needed memory and its input queue priority.

Request

Parameter	Value
URL	/jobs/update/{queue}/{jobid}
Method	PUT
Path	queue parameter is mandatory and defined on which queue you are seaching the jobs. The valid values could be input, running, output, routing jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	text/plain
Body	A set of attributes (affinity, domain, environment, memory and priority) that you can change of a job

Response

Status code	Description
200	OK - Returns true if it was able to purge the job, otherwise false. The TEXT format is: "true" or "false"
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Submitting a job

You can submit, passing JCL (by content or JEM URL), JCL type and runtime properties.

Request

Parameter	Value
URL	/jobs/submit
Method	PUT
Path	none
Query	type parameter is optional and defined JCL type. url parameter is optional (it's a JEM URL) and locates the JCL to submit reading it from GFS properties parameter is optional and sets the properties (key/value, comma separated) which can used at runtime
Content-Type	text/plain
Accept-Type	text/plain
Body	JCL to be submitted, in text format. It's optional because you can use url query parameter to locate this content from GFS

Response

Status code	Description
200	OK - Returns the ID of submitted job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Getting a job file tree with output files links

Provides a tree with all links to output files creates by job during its execution, currently located a specific queue.

Request

Parameter	Value
URL	/jobs/outputTree/{queue}/{jobid}
Method	GET
Path	queue parameter is mandatory and defined on which queue you are seaching the jobs. The valid values could be input, running, output, routing jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	application/json
Body	none

Response

Status code	Description
200	OK - Returns a output tree object
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Getting the content of a output job

Provides the content of a output file created by job during its execution, currently located a specific queue.

Request

Parameter	Value
URL	/jobs/outputFile/{queue}/{jobid}
Method	POST
Path	queue parameter is mandatory and defined on which queue you are seaching the jobs. The valid values could be input, running, output, routing jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	text/plain
Body	The output file item with all information to locate it

Response

Status code	Description
200	OK - Returns the content of a output file in text format
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Getting JCL of a job

Provides the JCL of a job, currently located a specific queue.

Request

Parameter	Value
URL	/jobs/jcl/{queue}/{jobid}
Method	GET
Path	queue parameter is mandatory and defined on which queue you are seaching the jobs. The valid values could be input, running, output, routing jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	text/plain
Body	none

Response

Status code	Description
200	OK - Returns the jcl of a job in text format
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Getting the system activity of a running job

Provides the system activity (in terms of memory and cpu consumed) of a job which is running.

Request

Parameter	Value
URL	/jobs/systemActivity/{jobid}
Method	GET
Path	jobid parameter is mandatory and specified the job id to search
Query	none
Content-Type	application/json
Accept-Type	application/json
Body	none

Response

Status code	Description
200	OK - Returns the system activity
400	Bad Request - The queue or job id passed as path parameters are not correct
401	Not Found - The job id passed as path parameters is not related to any job
500	Internal Server Error - The service had an exception
503	Service Unavailable - JEM cluster is not available.

Body format

This section described the JSON format of the BODY parameters to use in the requests and the BODY responses.

Jobs

It's a collection of job information:

[ job1,..., jobN]

Job

A job is described by the following JSON format:

{
  "id" : "job id",
  "name" : "job name",
  "user" : "user who submit the job",
  "orgUnit" : "group of user",
  "submittedTime" : submitted time in UTC (Long),
  "startedTime" : started time in UTC (Long),
  "endedTime" : ended time in UTC (Long),
  "jcl" : {
    "environment" : "environment of JEM",
    "domain" : "domain",
    "jobName" : "job name, read  by JCL",
    "affinity" : "affinity",
    "memory" : memory needed (Integer),
    "priority" : input priority (Integer),
    "hold" : if it's in hold (Boolean),
    "emailNotificationAddresses" : "mail addresses to notify the end of job",
    "user" : "user to use to executed the job",
    "mode" : "JCL format",
    "type" : "JCL type",
    "classPath" : "classpath to use to execute the job",
    "priorClassPath" : "classpath to use to execute the job to put before of standard classpath set by JEM",
    "java" : "which java runtime to use to execute the job",
    "properties" : "JCL properties",
    "content" : ALWAYS NULL,
    "contentToBeExecuted" : ALWAYS NULL
  },
  "memberId" : "Unique ID of JEM node where the job has been executed",
  "memberLabel" : "IP address and port of JEM node where the job has been executed",
  "processId" : "process ID of job execution",
  "result" : {
    "returnCode" : JOB exit code (Integer),
    "exceptionMessage" : "exception if ended not correctly"
  },
  "runningStatus" : if job in execution is waiting for resources or not (Integer),
  "routingInfo" : {
    "id" : "job id of routed job",
    "routedTime" : when job has been routed in UTC (Long),
    "submittedTime" : submitted time in UTC (Long),
    "environment" : "enviroment where the job has been routed for execution",
    "routingCommitted" : "if routing is committed",
    "outputCommitted" : if output has been committed (Boolean)
  },
  "nowait" : if has been submitted waitning the end or not (Boolean),
  "inputArguments" : [ "properties -D set during submitting job"],
  "currentStep" : {
    "name" : "name of step",
    "description" : "descritpion of step",
    "returnCode" : exit code of step (Integer),
    "exception" : "exception if ended not correctly"
  },
  "userSurrogated" : if the jobs muste be executed with surrogated user (Boolean)
}

Job Status

A job status is described by the following JSON format:

{
  "jobsInput" : [job1,..., jobN ],
  "jobsRunning" : [job1,..., jobN ],
  "jobsOutput" : [job1,..., jobN ],
  "jobsRouting" : [job1,..., jobN ],
}

Update job

Updating a job, you should provide the following JSON format:

{
  "affinity" : "list of affinity tags, comma separeted",
  "memory" : amount of requested memory (Integer),
  "priority" : priority to use in INPUT queue (Integer),
  "environment" : "environment where the job must be executed",
  "domain" : "environment where the job must be executed",
}

Output Tree

Tree of output file produced by job is described by the following JSON format:

{
  "jclContent" : "JCL content",
  "firstLevelItems" : [ outputl item 1, ..., output itemN ],
  "secondLevelItems" : [ [outputl item 1, ..., output itemN] ]
}

Output Item

The single requested item (to get the content) is described by the following JSON format:

{
  "label" : "name of output file",
  "parent" : "null if is the first level otherwise in which subfolfer the output file is present",
  "fileRelativePath" : "relatie path of the file on GFS"
}

System Activity

The job system activity when the job is running is described by the following JSON format:

{
  "active" : true is job is really ruunning (Boolean),
  "cpu" : amount of consumed CPU in seconds (Integer),
  "cpuPerc" : percent of CPU consumed in the interval (Double),
  "memory" : amount of consumed Memory in byte (Integer),
  "process" : {
    "pid" : process id (Integer),
    "command" : "OS command executed",
    "cpu" :  amount of consumed CPU in seconds (Integer),
    "memory" : amount of consumed Memory in byte (Integer),
    "children" : [ process1,... processN ]
  }
}