## Methods

### create

##### splunkjs.Service.Jobs.create

##### Endpoint: search/jobs

Creates a search job with a given search query and optional parameters, including `exec_mode` to specify the type of search:

- Use `exec_mode=normal` to return a search job ID immediately (default). Poll for completion to find out when you can retrieve search results.

- Use `exec_mode=blocking` to return the search job ID when the search has finished.

To run a oneshot search, which does not create a job but rather returns the search results, use `Service.Jobs.oneshotSearch`.

#### Syntax

create: function(query, params, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
query | String | The search query.
params | Object | A dictionary of properties for the search job. For a list of available parameters, see Search job parameters on Splunk Developer Portal.
callback | Function | A function to call with the created job: `(err, createdJob)`.

#### Source (lib/service.js:3207)

    create: function(query, params, callback) {
        // If someone called us with the default style of (params, callback),
        // lets make it work
        if (utils.isObject(query) && utils.isFunction(params) && !callback) {
            callback = params;
            params = query;
            query = params.search;
        }

        callback = callback || function() {};
        params = params || {};
        params.search = query;

        if ((params.exec_mode || "").toLowerCase() === "oneshot") {
            throw new Error("Please use splunkjs.Service.Jobs.oneshotSearch for exec_mode=oneshot");
        }

        if (!params.search) {
            callback("Must provide a query to create a search job");
            return;
        }
        var that = this;
        return this.post("", params, function(err, response) {
            if (err) {
                callback(err);
            }
            else {
                var job = new root.Job(that.service, response.data.sid, that.namespace);
                callback(null, job);
            }
        });
    },

### init

##### splunkjs.Service.Jobs.init

Constructor for `splunkjs.Service.Jobs`.

#### Syntax

init: function(service, namespace)

#### Parameters

Name | Type | Description
--- | --- | ---
service | splunkjs.Service | A `Service` instance.
namespace | Object | Namespace information: - `owner` (string): The Splunk username, such as "admin". A value of "nobody" means no specific user. The "-" wildcard means all users. - `app` (string): The app context for this resource (such as "search"). The "-" wildcard means all apps. - `sharing` (string): A mode that indicates how the resource is shared. The sharing mode can be "user", "app", "global", or "system".

#### Return

splunkjs.Service.Jobs.

A new `splunkjs.Service.Jobs` instance.

#### Source (lib/service.js:3182)

    init: function(service, namespace) {
        this._super(service, this.path(), namespace);
        // We perform the bindings so that every function works
        // properly when it is passed as a callback.
        this.create     = utils.bind(this, this.create);
    },

### instantiateEntity

##### splunkjs.Service.Jobs.instantiateEntity

Creates a local instance of a job.

#### Syntax

instantiateEntity: function(props)

#### Parameters

Name | Type | Description
--- | --- | ---
props | Object | The properties for this new job. For a list of available parameters, see Search job parameters on Splunk Developer Portal.

#### Return

splunkjs.Service.Job.

A new `splunkjs.Service.Job` instance.

#### Source (lib/service.js:3163)

    instantiateEntity: function(props) {
        var sid = props.content.sid;
        var entityNamespace = utils.namespaceFromProperties(props);
        return new root.Job(this.service, sid, entityNamespace);
    },

### oneshotSearch

##### splunkjs.Service.Jobs.oneshotSearch

##### Endpoint: search/jobs

Creates a oneshot search from a given search query and parameters.

#### Syntax

oneshotSearch: function(query, params, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
query | String | The search query.
params | Object | A dictionary of properties for the search: - `output_mode` (string): Specifies the output format of the results (XML, JSON, or CSV). - `earliest_time` (string): Specifies the earliest time in the time range to search. The time string can be a UTC time (with fractional seconds), a relative time specifier (to now), or a formatted time string. - `latest_time` (string): Specifies the latest time in the time range to search. The time string can be a UTC time (with fractional seconds), a relative time specifier (to now), or a formatted time string. - `rf` (string): Specifies one or more fields to add to the search.
callback | Function | A function to call with the results of the search: `(err, results)`.

#### Examples

     var jobs = service.jobs();
     jobs.oneshotSearch("search ERROR", {id: "myjob_123"}, function(err, results) {
         console.log("RESULT FIELDS": results.fields);
     });

#### Source (lib/service.js:3291)

    oneshotSearch: function(query, params, callback) {
            // If someone called us with the default style of (params, callback),
            // lets make it work
            if (utils.isObject(query) && utils.isFunction(params) && !callback) {
                callback = params;
                params = query;
                query = params.search;
            }

            callback = callback || function() {};
            params = params || {};
            params.search = query;
            params.exec_mode = "oneshot";

            if (!params.search) {
                callback("Must provide a query to create a search job");
            }

            var outputMode = params.output_mode || "json_rows";

            var path = this.qualifiedPath;
            var method = "POST";
            var headers = {};
            var post = params;
            var get = {output_mode: outputMode};
            var body = null;

            var req = this.service.request(
                path,
                method,
                get,
                post,
                body,
                headers,
                function(err, response) {
                    if (err) {
                        callback(err);
                    }
                    else {
                        callback(null, response.data);
                    }
                }
            );

            return req;
        }
    });

### path

##### splunkjs.Service.Jobs.path

Retrieves the REST endpoint path for this resource (with no namespace).

#### Syntax

path: function()

#### Source (lib/service.js:3151)

    path: function() {
        return Paths.jobs;
    },

### search

##### splunkjs.Service.Jobs.search

##### Endpoint: search/jobs

Creates a search job with a given search query and optional parameters, including `exec_mode` to specify the type of search:

- Use `exec_mode=normal` to return a search job ID immediately (default). Poll for completion to find out when you can retrieve search results.

- Use `exec_mode=blocking` to return the search job ID when the search has finished.

To run a oneshot search, which does not create a job but rather returns the search results, use `Service.Jobs.oneshotSearch`.

#### Syntax

search: function(query, params, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
query | String | The search query.
params | Object | A dictionary of properties for the search job. For a list of available parameters, see Search job parameters on Splunk Developer Portal. Note: This method throws an error if the `exec_mode=oneshot` parameter is passed in with the properties dictionary.
callback | Function | A function to call with the new search job: `(err, createdJob)`.

#### Examples

     var jobs = service.jobs();
     jobs.search("search ERROR", {id: "myjob_123"}, function(err, newJob) {
         console.log("CREATED": newJob.sid);
     });

#### Source (lib/service.js:3266)

    search: function(query, params, callback) {
        return this.create(query, params, callback);
    },

## Inherited Methods

### del

##### splunkjs.Service.Endpoint.del

Performs a relative DELETE request on an endpoint's path, combined with the parameters and a relative path if specified.

#### Syntax

del: function(relpath, params, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
relpath | String | A relative path to append to the endpoint path.
params | Object | A dictionary of entity-specific parameters to add to the query string.
callback | Function | A function to call when the request is complete: `(err, response)`.

#### Examples

     // Will make a request to {service.prefix}/search/jobs/123456
     var endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
     endpoint.delete("", {}, function() { console.log("DELETED"))});

#### Source (lib/service.js:695)

    del: function(relpath, params, callback) {
            var url = this.qualifiedPath;
            // If we have a relative path, we will append it with a preceding
            // slash.
            if (relpath) {
                url = url + "/" + relpath;
            }
            return this.service.del(
                url,
                params,
                callback
            );
        }
    });

### fetch

##### splunkjs.Service.Collection.fetch

Refreshes the resource by fetching the object from the server and loading it.

#### Syntax

fetch: function(options, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
options | Object | A dictionary of collection filtering and pagination options: - `count` (integer): The maximum number of items to return. - `offset` (integer): The offset of the first item to return. - `search` (string): The search query to filter responses. - `sort_dir` (string): The direction to sort returned items: “asc” or “desc”. - `sort_key` (string): The field to use for sorting (optional). - `sort_mode` (string): The collating sequence for sorting returned items: “auto”, “alpha”, “alpha_case”, or “num”.
callback | Function | A function to call when the object is retrieved: `(err, resource)`.

#### Source (lib/service.js:1283)

    fetch: function(options, callback) {
        if (!callback && utils.isFunction(options)) {
            callback = options;
            options = {};
        }
        callback = callback || function() {};

        options = options || {};
        if (!options.count) {
            options.count = 0;
        }

        var that = this;
        var req = that.get("", options, function(err, response) {
            if (err) {
                callback(err);
            }
            else {
                that._load(response.data);
                callback(null, that);
            }
        });

        return req;
    },

### fetchOnEntityCreation

##### splunkjs.Service.Collection.fetchOnEntityCreation

A static property that indicates whether to call `fetch` after an entity has been created. By default, the entity is not fetched because the endpoint returns (echoes) the new entity.

#### Source (lib/service.js:1151)

    fetchOnEntityCreation: false,

### get

##### splunkjs.Service.Endpoint.get

Performs a relative GET request on an endpoint's path, combined with the parameters and a relative path if specified.

#### Syntax

get: function(relpath, params, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
relpath | String | A relative path to append to the endpoint path.
params | Object | A dictionary of entity-specific parameters to add to the query string.
callback | Function | A function to call when the request is complete: `(err, response)`.

#### Examples

     // Will make a request to {service.prefix}/search/jobs/123456/results?offset=1
     var endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
     endpoint.get("results", {offset: 1}, function() { console.log("DONE"))});

#### Source (lib/service.js:631)

    get: function(relpath, params, callback) {
        var url = this.qualifiedPath;
        // If we have a relative path, we will append it with a preceding
        // slash.
        if (relpath) {
            url = url + "/" + relpath;
        }
        return this.service.get(
            url,
            params,
            callback
        );
    },

### item

##### splunkjs.Service.Collection.item

Returns a specific entity from the collection.

#### Syntax

item: function(id, namespace)

#### Parameters

Name | Type | Description
--- | --- | ---
id | String | The name of the entity to retrieve.
namespace | Object | Namespace information: - `owner` (string): The Splunk username, such as "admin". A value of "nobody" means no specific user. The "-" wildcard means all users. - `app` (string): The app context for this resource (such as "search"). The "-" wildcard means all apps. - `sharing` (string): A mode that indicates how the resource is shared. The sharing mode can be "user", "app", "global", or "system".

#### Examples

     var apps = service.apps();
     apps.fetch(function(err, apps) {
         var app = apps.item("search");
         console.log("Search App Found: " + !!app);
         // `app` is an Application object.
     });

#### Source (lib/service.js:1330)

    item: function(id, namespace) {
        if (utils.isEmpty(namespace)) {
            namespace = null;
        }

        if (!id) {
            throw new Error("Must suply a non-empty name.");
        }

        var fullPath = null;
        if (this._entitiesByName.hasOwnProperty(id)) {
            var entities = this._entitiesByName[id];

            if (entities.length === 1 && !namespace) {
                // If there is only one entity with the
                // specified name and the user did not
                // specify a namespace, then we just
                // return it
                return entities[0];
            }
            else if (entities.length === 1 && namespace) {
                // If we specified a namespace, then we
                // only return the entity if it matches
                // the full path
                fullPath = this.service.fullpath(entities[0].path(), namespace);
                if (entities[0].qualifiedPath === fullPath) {
                    return entities[0];
                }
                else {
                    return null;
                }
            }
            else if (entities.length > 1 && !namespace) {
                // If there is more than one entity and we didn't
                // specify a namespace, then we return an error
                // saying the match is ambiguous
                throw new Error("Ambiguous match for name '" + id + "'");
            }
            else {
                // There is more than one entity, and we do have
                // a namespace, so we try and find it
                for(var i = 0; i < entities.length; i++) {
                    var entity = entities[i];
                    fullPath = this.service.fullpath(entities[i].path(), namespace);
                    if (entity.qualifiedPath === fullPath) {
                        return entity;
                    }
                }
            }
        }
        else {
            return null;
        }
    },

### links

##### splunkjs.Service.Collection.links

Retrieves the links information for this collection, which is the URI of the resource relative to the management port of a Splunk instance.

#### Syntax

links: function()

#### Return

Object.

The links information.

#### Source (lib/service.js:1242)

    links: function() {
        return this._links;
    },

### list

##### splunkjs.Service.Collection.list

Retrieves a list of all entities in the collection.

#### Syntax

list: function(callback)

#### Parameters

Name | Type | Description
--- | --- | ---
callback | Function | A function to call with the list of entities: `(err, list)`.

#### Examples

     var apps = service.apps();
     apps.fetch(function(err, apps) {
         var appList = apps.list();
         console.log(appList.length);
     });

#### Source (lib/service.js:1452)

    list: function(callback) {
            callback = callback || function() {};

            return utils.clone(this._entities);
        }
    });

### paging

##### splunkjs.Service.Collection.paging

Retrieves the author information for this collection.

#### Syntax

paging: function()

#### Return

String.

The author.

#### Source (lib/service.js:1253)

    paging: function() {
        return this._paging;
    },

### post

##### splunkjs.Service.Endpoint.post

Performs a relative POST request on an endpoint's path, combined with the parameters and a relative path if specified.

#### Syntax

post: function(relpath, params, callback)

#### Parameters

Name | Type | Description
--- | --- | ---
relpath | String | A relative path to append to the endpoint path.
params | Object | A dictionary of entity-specific parameters to add to the body.
callback | Function | A function to call when the request is complete: `(err, response)`.

#### Examples

     // Will make a request to {service.prefix}/search/jobs/123456/control
     var endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
     endpoint.post("control", {action: "cancel"}, function() { console.log("CANCELLED"))});

#### Source (lib/service.js:663)

    post: function(relpath, params, callback) {
        var url = this.qualifiedPath;
        // If we have a relative path, we will append it with a preceding
        // slash.
        if (relpath) {
            url = url + "/" + relpath;
        }
        return this.service.post(
            url,
            params,
            callback
        );
    },

### properties

##### splunkjs.Service.Resource.properties

Retrieves the current properties for this resource.

#### Syntax

properties: function()

#### Return

Object.

The properties.

#### Source (lib/service.js:797)

    properties: function() {
        return this._properties;
    },

### state

##### splunkjs.Service.Resource.state

Retrieves the current full state (properties and metadata) of this resource.

#### Syntax

state: function()

#### Return

Object.

The current full state of this resource.

#### Source (lib/service.js:808)

    state: function() {
            return this._state;
        }
    });

### updated

##### splunkjs.Service.Collection.updated

Retrieves the updated time for this collection.

#### Syntax

updated: function()

#### Return

String.

The updated time.

#### Source (lib/service.js:1264)

    updated: function() {
        return this._updated;
    },