Splunk.Job

Important notice: As part of Advanced XML deprecation, the Module System is officially deprecated beginning with Splunk Enterprise 6.3. For more information, see Advanced XML Deprecation.

areResultsTransformed()

The areResultsTransformed() method indicates whether or not search results are transformed. Results are transformed when search commands, such as timechart and stats, have populated the results set with different data than the events set. Use this method to determine whether to retrieve data from the job events set or results set.

Synopsis

results = areResultsTransformed()

Return Value

Boolean Results endpoint returns transformed results indication:
true = Search results are transformed.
false = Search results are not transformed.

Example

var context = this.getContext();
var search = context.get('search');
var entityName;
if (search.job.areResultsTransformed()) {

  entityName = 'results';

} else {

  entityName = 'events';

}
console.log(entityName);

canBeAutoCancelled()

The canBeAutoCancelled() method checks if the current job can be auto-canceled. A job can be auto-canceled if it is not a real-time search or has not been saved by calling save(). A job can also be auto-canceled if it has been set to auto-cancelable, either at instantiation or by calling setAsAutoCancellable().

Jobber attempts to automatically cancel a job when polling indicates that the job has become inactive, after a defined time interval, or if the browser page closed.

Synopsis

cancel = canBeAutoCancelled()

Return Value

Boolean Job can be auto-canceled indication:
true = Job can be auto-canceled.
false = Job cannot be auto-canceled.

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.canBeAutoCancelled()) {

   console.log('job can be auto-canceled.');

} else {

   console.log('job cannot be auto-canceled.');

cancel()

The cancel() method cancels the current job, if it has not already been canceled. If the job is successfully canceled, the job SID is set to null.

Calling this method raises the jobCanceled and jobStatusChanged events.

Synopsis

status = cancel( onSuccess, onFailure )

Parameters

onSuccess	`Function`	(Optional) Function to be called on successful cancellation.
onFailure	`Function`	(Optional) Function to be called on unsuccessful cancellation.

Return Value

Boolean Cancel request status:
Undefined = Job canceled.
False = Job already canceled or could not be canceled.

Throws

Error: "Cannot call the job endpoint if we dont have an sid yet"

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.cancel(function() {

        console.log('Handle successful job cancellation.');
     }, function() {
        console.log('Handle failure to cancel job.');
     }) == false)
  console.log('job already canceled or could not be canceled.');

finalize()

If the current job has not yet finished, the finalize() method stops the job, unpausing the job if it has been paused.

This method raises the jobFinalized and jobStatusChanged events.

Because we cannot predict when job polling will finish it is possible to request a job be paused that, on the server, is actually done. The first time the server indicates a job is paused or finalized, a jobPaused event is triggered. If the job state is also set to done, jobProgress and jobDone events are also triggered.

Synopsis

status = finalize( onSuccess, onFailure )

Parameters

onSuccess	`Function`	(Optional) Function to be called on successful finalization.
onFailure	`Function`	(Optional) Function to be called on unsuccessful finalization.

Return Value

Boolean Job finalization request status:
undefined = Finalize request made to the server.
false = Job has already finished.

Throws

Error: "Cannot call the job endpoint if we dont have an sid yet"

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.finalize(function() {

        console.log('Handle successful job finalization.');
     }, function() {
        console.log('Handle failure to finalize job.');
     }) == false)
  console.log('Job has already completed.');

getCreateTime()

The getCreateTime() method gets the current job creation time. The job creation time is set when the job is posted to the backend, and getCreateTime() expects the date to be stored as seconds since 01.01.1970.

Note: The return value is undefined if the search didn't previously call setCreateTime().

Synopsis

time = getCreateTime()

Return Value

false = Job creation time not previously set.
Date() object = Job creation time.

Example

var context = this.getContext();
var search = context.get('search');

search.job.setCreateTime(new Date().getTime()/1000); var createTime = search.job.getCreateTime(); console.log('Job created at ' + createTime.toString());

getCursorTime()

Cursor time is the time after which no events have been scanned. Cursor time can be used to indicate job progress, where:

doneProgress = (latestTime - cursorTime) / (latestTime - earliestTime)

The getCursorTime() method gets the current job cursor time.

Note: For searches distributed over multiple search heads, this is the latest cursor time of all searches.

Synopsis

time = getCursorTime()

Return Value

false = Cursor time not yet set.
Date() object = Cursor time.

Example

var context = this.getContext();
var search = context.get('search');
var cursorTime = search.job.getCursorTime();
if (cursorTime == false)

  console.log('Job cursor time not set.');

else

  console.log('Current job cursor time is ' + cursorTime.toString());

getDoneProgress()

Job progress is calculated as:

doneProgress = (latestTime - cursorTime) / (latestTime - earliestTime)

The getDoneProgress() method gets a value representing the percentage of job completion, for the current job.

Synopsis

progress = getDoneProgress()

Return Value

Float Job progress from 0.0 to 1.0, representing zero percent to 100 percent complete.

Example

var context = this.getContext();
var search = context.get('search');
var cursorTime = search.job.getCursorTime();
var jobProgress = Math.round(search.job.getDoneProgress() * 100);
console.log (sprintf(_('Job is %s%% complete'), jobProgress));

getEventAvailableCount()

The getEventAvailableCount() method gets the number of events available for export, for the current job.

Note: If there are no status buckets set for the current job, this method returns the result count (see getResultCount() ). This is the main difference between this method and getEventCount().

Synopsis

count = getEventAvailableCount()

Return Value

Integer Number of available events for the current job.

Example

var context = this.getContext();
var search = context.get('search');
var availableEvents = search.job.getEventAvailableCount();
console.log('Available event count = ' + availableEvents.toString());

getEventCount()

The getEventCount() method gets the number of events advertised for the current job.

Note: This method and getEventAvailableCount() often return different values. This method always returns the total number of events returned by the current job.

Synopsis

count = getEventCount()

Return Value

Integer Number of available events for the current job.

Example

var context = this.getContext();
var search = context.get('search');
console.log('Number of events in the current job = ' + search.job.getEventCount().toString());

getEventFieldCount()

The getEventFieldCount() method gets the number of unique fields available within the current job. Jobs with zero status buckets always advertise zero fields.

Synopsis

results = getEventFieldCount()

Return Value

Integer Number of available fields for the current job.

Example

var context = this.getContext();
var search = context.get('search');

console.log('Number of unique fields in the current job = ' + search.job.getEventFieldCount().toString());

getEventSearch()

The getEventSearch() method gets the part of the search string preceding the first transforming command, such as stats or timechart commands.

Synopsis

eventSearch = getEventSearch()

Return Value

String The part of the search string preceding the first transforming command.

Example

var context = this.getContext();
var search = context.get('search');
console.log('Base search command: ' + search.job.getEventSearch());

getEventSorting()

The getEventSorting() method gets the event sorting order for the current job.

Synopsis

sort = getEventSorting()

Return Value

String Event sorting order:
desc = Descending order.
none = (Default) No sorting.
realtime = Recent events are prepended to the event set.

Example

var context = this.getContext();
var search = context.get('search');

var context = this.getContext();
var search = context.get('search');
console.log('Search ID: ' + search.job.getSID());

getStatusBuckets()

The getStatusBuckets() method gets the number of status buckets for the current job.

Status buckets represent the status_buckets parameter in the Splunk REST API endpoint /services/search/jobs. Essentially, if status_buckets is zero, raw events are not persisted for the job. If status_buckets is greater than zero, raw events persist for the job.

Synopsis

buckets = getStatusBuckets()

Return Value

Integer Number of status buckets requested for the current job.

Example

var context = this.getContext();
var search = context.get('search');
console.log('Number of status buckets = ' + search.job.getStatusBuckets().toString());

getTimeRange()

The getTimeRange() method gets a Splunk.TimeRange instance representing the current job data absolute time range.

Synopsis

timeRange = getTimeRange()

Return Value

Object Splunk.TimeRange instance representing the absolute time range of the current job data.

Example

var context = this.getContext();
var search = context.get('search');

console.log('Timerange: ' + search.job.getTimeRange().toString());

getTimeSinceLastProgress()

The getTimeSinceLastProgress() method gets the time interval since a progress event was fired for the current job.

Synopsis

time = getTimeSinceLastProgress()

Return Value

Object A Date() object representing the time since a progress event was fired, in milliseconds.

Example

var context = this.getContext();
var search = context.get('search');
var idleTime = search.job.getTimeSinceLastProgress();
console.log('it has been ' + idleTime.toString() + ' since the job last showed progress');

isCanceled()

The isCanceled() method checks if the current job has been canceled.

Synopsis

status = isCanceled()

Return Value

Boolean Job canceled status:
true = Job is canceled.
false = Job is not canceled.

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.isCanceled()) {

  console.log('job is cancelled!');

} else {

  console.log('job is active!');

isDone()

The isDone() method checks if the current job has completed processing.

Synopsis

status = isDone()

Return Value

Boolean Processing complete status:
true = Processing is complete.
false = Processing is NOT complete.

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.isDone()) {

  console.log('job has completed processing!');

} else {

  console.log('job has not completed processing!');

isEventStreaming()

The isEventStreaming() method checks if the current job permits partial events and results retrieval.

Synopsis

status = isEventStreaming()

Return Value

Boolean Job permits retrieval of partial events and results indication:
true = Job permits partial event or result streaming.
false = Job does not permit partial event or result streaming.

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.isEventStreaming()) {

  console.log('Job permits partial event streaming!');

} else {

  console.log('Job does not permit partial event streaming!');

isFinalized()

The isFinalized() method checks the current job was stopped (finalized) before it completed.

Synopsis

results = isFinalized()

Return Value

Boolean Job finalized state:
true = Job stopped before it completed.
false = Job was not stopped before it completed.

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.isFinalized()) {

   console.log('job stopped before it completed!');

} else {

   console.log('job was NOT stopped before it completed!');

isPaused()

The isPaused() method checks if the current job is paused. A job that has completed is considered not paused.

Synopsis

results = isPaused()

Return Value

Boolean Job paused state:
true = Job is paused.
false = Job is not paused.

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.isPaused()) {

   console.log('Current job is paused!');

} else {

   console.log('Current job is NOT paused!');

isPreviewable()

The isPreviewable() method checks if results can be previewed for the current job.

Synopsis

results = isPreviewable()

Return Value

Boolean Job preview permission: true = Job can be previewed. false = Job cannot be previewed.

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.isPreviewable()) {

   console.log('Current job results are previewable!');

} else {

   console.log('Current job results are NOT previewable!');

isRealTimeSearch()

The isRealTimeSearch() method checks if the current job is a real-time search.

Real-time search jobs cannot be auto-canceled.

See Search and report in real time for a discusion of real-time searches.

Synopsis

results = isRealTimeSearch()

Return Value

Boolean Search job type:
true = Job is a real-time search.
false = Job is not a real-time search.

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.isRealTimeSearch()) {

   console.log('Current job is a real-time search!');

} else {

   console.log('Current job is NOT a real-time search!');

isRunning()

The isRunning() method checks if the current job is done or paused. If the job is not done or paused, the job is running.

Synopsis

results = isRunning()

Return Value

Boolean Job running state: true = Job is not done or paused (running). false = Job is done or paused (not running).

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.isRunning()) {

   console.log('Current job is running!');

} else {

   console.log('Current job is NOT running!');

isSaved()

The isSaved() method checks if the current job is saved. A saved job is not auto-cancellable by the UI.

Synopsis

results = isSaved()

Return Value

Boolean Job saved state:
true = Job is saved.
false = Job is not saved.

Example

var context = this.getContext();
var search = context.get('search');
if (search.job.isSaved()) {

   console.log('Current job is saved!');

} else {

   console.log('Current job is NOT saved!');

makeWorldReadable()

The makeWorldReadable() method sets the current job access control to world readable. No error is indicated, if job access control is already world readable.

Synopsis

makeWorldReadable( onSuccess, onFailure)

Parameters

onSuccess	`Function`	(Optional) Function to execute upon successful operation.
onFailure	`Function`	(Optional) Function to execute upon unsuccessful operation.

Example

var context = this.getContext();
var search = context.get('search');
search.job.makeWorldReadable(

       function() { console.log('Current job access control set to world readable.'); },
       function() { console.log('Failed to set current job access control to world readable.'); } );

pause()

The pause() method suspends processing for the current job until either unpause(), save(), finalize(), or cancel() is requested.

Because you cannot predict when jobs are polled, it is possible to request that a job be paused that has already completed. The first time the server detects a job is paused triggers a jobPaused event. If the server also detects a job has completed, jobProgress and jobDone events are triggered.

Synopsis

pause( onSuccess, onFailure)

Parameters

onSuccess	`Function`	(Optional) Function to execute upon successful operation.
onFailure	`Function`	(Optional) Function to execute upon unsuccessful operation.

Example

var context = this.getContext();
var search = context.get('search');
if (!search.job.isDone()) {

  search.job.pause(
     function() { console.log('Current job successfully paused!'); },
     function() { console.log('Failed to pause current job!'); } );

} else {

  console.log('Current job has already completed!');

save()

The save() method saves the current job, which permits the job to persist, indefinitely. Calling this method has no effect if the job has already completed, although the save operation will be considered successful. A saved job cannot be auto-canceled by the UI or by calling setAsAutoCancellable().

Synopsis

save( onSuccess, onFailure)

Parameters

onSuccess	`Function`	(Optional) Function to execute upon successful operation.
onFailure	`Function`	(Optional) Function to execute upon unsuccessful operation.

Example

var context = this.getContext();
var search = context.get('search');
search.job.save(

   function() { console.log('Current job successfully saved!'); },
   function() { console.log('Failed to save the current job!'); } );

setAsAutoCancellable()

The setAsAutoCancellable() method sets whether or not the current job can be auto-canceled. Saving a job by calling save(), implicitly, prevents the job from being canceled.

Splunk attempts to automatically cancel jobs when polling indicates that the job has been inactive for a predefined time interval, or when the browser page is closed. Some types of jobs, such as real-time or saved jobs, are not intended to be canceled so this method must be called to prevent those types of jobs from being canceled.

Synopsis

setAsAutoCancellable( cancelableFlag )

Parameters

cancelableFlag Boolean Job auto-cancelable specification:
true = Job is auto-cancelable.
false = Job is not auto-cancelable.

Example

var context = this.getContext();
var search = context.get('search');
search.job.setAsAutoCancellable(true);

setLastProgressTime()

The setLastProgressTime() method sets the last progress time for the current job to the current client browser time.

Synopsis

setLastProgressTime()

Example

var context = this.getContext();
var search = context.get('search');
search.job.setLastProgressTime();

setPreviewable()

The setPreviewable() method sets whether or not job results can be previewed before the job completes.

search.job.setTTL(

       function() { console.log('Current job TTL successfully set.'); },
       function() { console.log('Failed to set current job TTL.'); },
       24*3600);

touch()

The touch() method touches the job, using the REST API, to refresh the time-to-live so the job is not auto- canceled or expired. If successful, this generates a jobStatusChanged event.

Synopsis

touch( onSuccess, onFailure)

Parameters

onSuccess	`Function`	(Optional) Function to run on successful operation.
OnFailure	`Function`	(Optional) Function to run on unsuccessful operation.

Example

var context = this.getContext();
var search = context.get('search');
search.job.touch();

undoWorldReadable()

The undoWorldReadable() method sets the current job access control to not world-readable. An error is not indicated if the job is already set to not world readable.

Synopsis

results = undoWorldReadable( onSuccess, onFailure)

Parameters

onSuccess	`Function`	(Optional) Function to call on successful operation.
onFailure	`Function`	(Optional) Function to call on unsuccessful operation.

Return Value

Undefined

Example

var context = this.getContext();
var search = context.get('search');
search.job.undoWorldReadable(

       function() { console.log('Current job access control set to not world readable.'); },
       function() { console.log('Failed to set current job access control to not world readable.'); } );

);

unpause()

The unpause() method unsuspends the current job.

Synopsis

unpause( onSuccess, onFailure)

Parameters

onSuccess	`Function`	(Optional) Function to call on successful operation.
onFailure	`Function`	(Optional) Function to call on unsuccessful operation.

Example

var context = this.getContext();
var search = context.get('search');
search.job.unpause(function() { console.log('Successfully unpaused job.'); },

                  function() { console.log('Failed to unpause job.'); } );

unsave()

The unsave() method sets the current job status to not saved, permitting the job to be canceled.

Synopsis

unsave( onSuccess, onFailure)

Parameters

onSuccess	`Function`	(Optional) Function to call on successful operation.
onFailure	`Function`	(Optional) Function to call on unsuccessful operation.

Example

var context = this.getContext();
var search = context.get('search');
search.job.unsave(

   function() { console.log('Current job successfully unsaved!'); },
   function() { console.log('Failed to unsave the current job!'); } );

Related answers from Splunk Community

Splunk.Job

areResultsTransformed()

Synopsis

Return Value

Example

See Also

canBeAutoCancelled()

Synopsis

Return Value

Example

See Also

cancel()

Synopsis

Parameters

Return Value

Throws

Example

See Also

finalize()

Synopsis

Parameters

Return Value

Throws

Example

See Also

getCreateTime()

Synopsis

Return Value

Example

getCursorTime()

Synopsis

Return Value

Example

See Also

getDoneProgress()

Synopsis

Return Value

Example

See Also

getEventAvailableCount()

Synopsis

Return Value

Example

See Also

getEventCount()

Synopsis

Return Value

Example

See Also

getEventFieldCount()

Synopsis

Return Value

Example

getEventSearch()

Synopsis

Return Value

Example

See Also

getEventSorting()

Synopsis

Return Value

Example

getResultCount()

Synopsis

Return Value

Example

See Also

getScanCount()

Synopsis

Return Value

Example