Splunk® Enterprise

Module System Reference

Splunk Enterprise version 7.3 is no longer supported as of October 22, 2021. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.

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);

See Also

getStatusBuckets()

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.');

}

See Also

isRealTimeSearch()
save()
setAsAutoCancellable()

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.');

See Also

setAsAutoCancellable()
canBeAutoCancelled()

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.');

See Also

isDone()
isFinalized()

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());

See Also

getDoneProgress()

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));

See Also

isDone()
getCursorTime()

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());

See Also

getEventCount()
getResultCount()
getScanCount()

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());

See Also

getEventAvailableCount()
getResultCount()
getScanCount()

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());

See Also

getSearch()

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');

console.log('Event sorting order: ' + search.job.getEventSorting());

getResultCount()

The getResultCount() method gets the number of results for the current job. If the job is preview-enabled, meaning that partial results are available before the job is done, this method returns the number of partial results.

Synopsis

count = getResultCount()

Return Value

Integer Number of results within the current job.

Example

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

console.log('Result count = ' + search.job.getResultCount().toString());

See Also

getEventAvailableCount()
getEventCount()
getScanCount()

getScanCount()

The getScanCount() method gets the number of events scanned by the current job in compiling the event or result set.

Synopsis

count = getScanCount()

Return Value

Integer Number of scanned events.

Example

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

console.log('Scan count = ' + search.job.getScanCount().toString());

See Also

getEventAvailableCount()
getEventCount()
getResultCount()

getSearch()

The getSearch() method gets the current job search string.

Synopsis

search = getSearch()

Return Value

String Current job search string.

Example

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

console.log('Search string: ' + search.job.getSearch());

See Also

getSearchId()
getSID()

getSearchId()

The getSearchId() getter method gets the current job search identifier.

Synopsis

searchID = getSearchId()

Return Value

String Current job search identifier.

Example

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

console.log('Search ID: ' + search.job.getSearchId());

See Also

getSearch()
getSID()
setSearchId()
setSID()

getSID()

The getSID() getter method gets the current job search identifier. This method calls getSearchId().

Synopsis

searchID = getSID()

Return Value

String Current job search identifier.

Example

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

console.log('Search ID: ' + search.job.getSID());

See Also

getSearch()
getSearchId()
setSID()

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());

See Also

areResultsTransformed()

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');

See Also

setLastProgressTime()

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!');

}

See Also

isDone()
isEventStreaming()
isFinalized()
isPaused()
isPreviewable()
isRealTimeSearch()
isRunning()
isSaved()

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!');

}

See Also

getDoneProgress()
isCanceled()
isEventStreaming()
isFinalized()
isPaused()
isPreviewable()
isRealTimeSearch()
isRunning()
isSaved()

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!');

}

See Also

isCanceled()
isEventStreaming()
isFinalized()
isPaused()
isPreviewable()
isRealTimeSearch()
isRunning()
isSaved()

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!');

}

See Also

isCanceled()
isDone()
isEventStreaming()
isPaused()
isPreviewable()
isRealTimeSearch()
isRunning()
isSaved()

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!');

}

See Also

isCanceled()
isDone()
isEventStreaming()
isFinalized()
isPreviewable()
isRealTimeSearch()
isRunning()
isSaved()
pause()
unpause()

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!');

}

See Also

isCanceled()
isDone()
isEventStreaming()
isFinalized()
isPaused()
isRealTimeSearch()
isRunning()
isSaved()
setPreviewable()

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!');

}

See Also

canBeAutoCancelled()
isCanceled()
isDone()
isEventStreaming()
isFinalized()
isPaused()
isPreviewable()
isRunning()
isSaved()

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!');

}

See Also

isCanceled()
isDone()
isEventStreaming()
isFinalized()
isPaused()
isPreviewable()
isRealTimeSearch()
isSaved()
pause()

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!');

}

See Also

isCanceled()
isDone()
isEventStreaming()
isFinalized()
isPaused()
isPreviewable()
isRealTimeSearch()
isRunning()
save()
unsave()

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.'); } );

See Also

undoWorldReadable()

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!');

}

See Also

isDone()
isPaused()
isRunning()
unPause()

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!'); } );

See Also

canBeAutoCancelled()
isSaved()
setAsAutoCancellable()
unsave()

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);

See Also

canBeAutoCancelled()
save()

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();

See Also

getTimeSinceLastProgress()

setPreviewable()

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

Note: Setting preview mode impacts search performance, considerably.

Synopsis

setPreviewable( mode )

Parameters

mode Boolean Preview mode:
true = Job results can be previewed.
false = Job results cannot be previewed.

Example

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

search.job.setPreviewable(true);

See Also

isPreviewable()

setSearchId()

The setSearchId() method sets the current job search identifier to the specified value.

Synopsis

setSearchId( searchID )

Parameters

searchID String Search identifier.

Example

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

search.job.setSearchId("TEST_HARNESS_MODE_ID_" + (20000*Math.random()));

See Also

getSearchId()
getSID()
setSID()

setSID()

The setSID() method sets the current job search identifier to the specified value. This method calls setSearchId().

Synopsis

setSID( searchID )

Parameters

searchID String Search identifier.

Example

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

search.job.setSID("TEST_HARNESS_MODE_ID_" + (20000*Math.random()));

See Also

getSearchId()
getSID()
setSearchId()

setTTL()

The setTTL() method sets the current job time-to-live to the specified value so the job is not auto- canceled or expired. If successful, this generates a jobStatusChanged event.

Synopsis

setTTL( onSuccess, onFailure, ttl)

Parameters

onSuccess Function Function to run on success of operation.
onFailure Function Function to run on failure of operation.
ttl Integer Current job time-to-live, in seconds.

Example

search.job.setTTL(

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

See Also

touch()

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();

See Also

setTTL()

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.'); } );

);

See Also

makeWorldReadable()

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.'); } );

See Also

isPaused()
pause()

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!'); } );

See Also

isSaved()
save()

Last modified on 12 August, 2019
Splunk.Context   Splunk.Search

This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9


Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters