Summary: Nested Classes | Constants | Methods | Inherited Methods | [Expand All]

public class

RundeckClient

extends Object
implements Serializable

java.lang.Object
↳	org.rundeck.api.RundeckClient

Class Overview

Rundeck API client.

There are three methods for authentication : login-based or token-based or session-based. Login authentication requires both a "login" and a "password". Token-based requires a "token" (also called "auth-token"). See the Rundeck documentation for generating such a token.

Session-based authentication allows re-use of a previous login session. See testAuth().

Usage :


  // using login-based authentication :
 RundeckClient rundeck = RundeckClient.builder()
                           .url("http://localhost:4440")
                           .login("admin", "admin").build();
 // or for a token-based authentication :
 RundeckClient rundeck = RundeckClient.builder()
                           .url("http://localhost:4440")
                           .token("PDDNKo5VE29kpk4prOUDr2rsKdRkEvsD").build();

 List<RundeckProject> projects = rundeck.getProjects();

 RundeckJob job = rundeck.findJob("my-project", "main-group/sub-group", "job-name");
 RundeckExecution execution = rundeck.triggerJob(job.getId(),
                                                 new OptionsBuilder().addOption("version", "1.2.0").toProperties());

 List<RundeckExecution> runningExecutions = rundeck.getRunningExecutions("my-project");

 rundeck.exportJobsToFile("/tmp/jobs.xml", FileType.XML, "my-project");
 rundeck.importJobs("/tmp/jobs.xml", FileType.XML);

Summary

Nested Classes
enum	RundeckClient.Version	Supported version numbers

Constants
String	API_ENDPOINT	End-point of the API
int	API_VERSION	Version of the API supported
long	DEFAULT_POOLING_INTERVAL	Default value for the "pooling interval" used when running jobs/commands/scripts
TimeUnit	DEFAULT_POOLING_UNIT	Default unit of the "pooling interval" used when running jobs/commands/scripts
String	JOBS_IMPORT
String	STORAGE_KEYS_PATH
String	STORAGE_ROOT_PATH

Public Methods
RundeckAbort	abortExecution(Long executionId) Abort an execution (identified by the given ID).
RundeckAbort	abortExecution(Long executionId, String asUser) Abort an execution (identified by the given ID).
static RundeckClientBuilder	builder() Create a builder for RundeckClient
RundeckProject	createProject(String projectName, Map<String, String> configuration) Create a new project, and return the new definition
DeleteExecutionsResponse	deleteAllJobExecutions(String jobId) Delete all executions for a job specified by a job ID
boolean	deleteApiToken(String token) Delete an existing token@return
void	deleteExecution(Long executionId) Delete a single execution, identified by the given ID
DeleteExecutionsResponse	deleteExecutions(Set<Long> executionIds) Delete a set of executions, identified by the given IDs
String	deleteJob(String jobId) Delete a single job, identified by the given ID
RundeckJobDeleteBulk	deleteJobs(List<String> jobIds) Delete multiple jobs, identified by the given IDs
void	deleteKey(String path) Delete an key file
void	deleteProject(String projectName) Delete a project
void	deleteProjectConfig(String projectName, String key) Set a single project configuration property value
void	deleteProjectFile(String projectName, String filename) Delete a project readme.md or motd.md
boolean	equals(Object obj)
InputStream	exportJob(String format, String jobId) Export the definition of a single job, identified by the given ID
InputStream	exportJob(FileType format, String jobId) Export the definition of a single job, identified by the given ID
void	exportJobToFile(String filename, String format, String jobId) Export the definition of a single job (identified by the given ID)
void	exportJobToFile(String filename, FileType format, String jobId) Export the definition of a single job (identified by the given ID)
InputStream	exportJobs(String format, String project) Export the definitions of all jobs that belongs to the given project
InputStream	exportJobs(String format, String project, String jobFilter, String groupPath, String... jobIds) Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)
InputStream	exportJobs(FileType format, String project) Export the definitions of all jobs that belongs to the given project
InputStream	exportJobs(FileType format, String project, String jobFilter, String groupPath, String... jobIds) Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)
void	exportJobsToFile(String filename, String format, String project) Export the definitions of all jobs that belongs to the given project
void	exportJobsToFile(String filename, String format, String project, String jobFilter, String groupPath, String... jobIds) Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)
void	exportJobsToFile(String filename, FileType format, String project) Export the definitions of all jobs that belongs to the given project
void	exportJobsToFile(String filename, FileType format, String project, String jobFilter, String groupPath, String... jobIds) Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)
int	exportProject(String projectName, File out) Convenience method to export the archive of a project to the specified file.
int	exportProject(String projectName, OutputStream out) Export the archive of a project to the specified outputstream
RundeckJob	findJob(String project, String groupPath, String name) Find a job, identified by its project, group and name.
String	generateApiToken(String user) Generate an API token for a user.@return
InputStream	generateToken(String username) Generate a new token and get the result page (which is the html page of the user's profile)
RundeckToken	getApiToken(String token) Return user info for an existing token
RundeckExecution	getExecution(Long executionId) Get a single execution, identified by the given ID
RundeckOutput	getExecutionOutput(Long executionId, int offset, int lastlines, long lastmod, int maxlines) Get the execution output of the given job
RundeckOutput	getExecutionOutput(Long executionId, int offset, long lastmod, int maxlines) Get the execution output of the given job
RundeckOutput	getExecutionOutputForNode(Long executionId, String nodeName, int offset, int lastlines, long lastmod, int maxlines) Get the execution output of the given execution on the specified node
RundeckOutput	getExecutionOutputForNodeAndStep(Long executionId, String nodeName, String stepCtx, int offset, int lastlines, long lastmod, int maxlines) Get the execution output of the given execution for the specified step
RundeckOutput	getExecutionOutputForStep(Long executionId, String stepCtx, int offset, int lastlines, long lastmod, int maxlines) Get the execution output of the given execution for the specified step
RundeckOutput	getExecutionOutputState(Long executionId, boolean stateOnly, int offset, long lastmod, int maxlines) Get the execution state output sequence of the given job
RundeckExecutionState	getExecutionState(Long executionId) Get the execution state of the given execution
PagedResults<RundeckExecution>	getExecutions(ExecutionQuery query, Long max, Long offset) Get executions based on query parameters
RundeckHistory	getHistory(String project) Get the (events) history for the given project
RundeckHistory	getHistory(String project, Long max, Long offset) Get the (events) history for the given project
RundeckHistory	getHistory(String project, String recent) Get the (events) history for the given project
RundeckHistory	getHistory(String project, String recent, Long max, Long offset) Get the (events) history for the given project
RundeckHistory	getHistory(String project, String jobId, String reportId, String user) Get the (events) history for the given project
RundeckHistory	getHistory(String project, String jobId, String reportId, String user, Long max, Long offset) Get the (events) history for the given project
RundeckHistory	getHistory(String project, String jobId, String reportId, String user, String recent, Date begin, Date end, Long max, Long offset) Get the (events) history for the given project
RundeckHistory	getHistory(String project, String user, String recent, List<String> includeJobNames, List<String> excludeJobNames, Date begin, Date end, Long max, Long offset) Get the (events) history for the given project
RundeckHistory	getHistory(String project, Date begin, Date end) Get the (events) history for the given project
RundeckHistory	getHistory(String project, Date begin, Date end, Long max, Long offset) Get the (events) history for the given project
RundeckJob	getJob(String jobId) Get the definition of a single job, identified by the given ID
List<RundeckExecution>	getJobExecutions(String jobId) Get the executions of the given job
List<RundeckExecution>	getJobExecutions(String jobId, String status) Get the executions of the given job
List<RundeckExecution>	getJobExecutions(String jobId, String status, Long max, Long offset) Get the executions of the given job
List<RundeckExecution>	getJobExecutions(String jobId, RundeckExecution.ExecutionStatus status) Get the executions of the given job
List<RundeckExecution>	getJobExecutions(String jobId, RundeckExecution.ExecutionStatus status, Long max, Long offset) Get the executions of the given job
List<RundeckJob>	getJobs() List all jobs (for all projects)
List<RundeckJob>	getJobs(String project) List all jobs that belongs to the given project
List<RundeckJob>	getJobs(String project, String jobFilter, String groupPath, String... jobIds) List the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)
KeyResource	getKey(String path) Get metadata for an key file
String	getLogin()
RundeckNode	getNode(String name, String project) Get the definition of a single node
List<RundeckNode>	getNodes() List all nodes (for all projects)
List<RundeckNode>	getNodes(String project) List all nodes that belongs to the given project
List<RundeckNode>	getNodes(String project, Properties nodeFilters) List nodes that belongs to the given project
InputStream	getOutput(String executionId) Get the output of a job execution
String	getPassword()
InputStream	getProfilePage(String username) Get the html page of the user's profile
RundeckProject	getProject(String projectName) Get the definition of a single project, identified by the given name
ProjectConfig	getProjectConfig(String projectName) Return the configuration of a project
String	getProjectConfig(String projectName, String key) Get a single project configuration key
List<RundeckProject>	getProjects() List all projects
int	getPublicKeyContent(String path, File out) Get content for a public key file
int	getPublicKeyContent(String path, OutputStream out) Get content for a public key file
List<RundeckExecution>	getRunningExecutions() Get all running executions (for all projects)
List<RundeckExecution>	getRunningExecutions(String project) Get the running executions for the given project
String	getSessionID()
RundeckSystemInfo	getSystemInfo() Get system informations about the Rundeck server
String	getToken()
String	getUrl()
int	hashCode()
ArchiveImport	importArchive(String projectName, File archiveFile, boolean includeExecutions, boolean preserveJobUuids) Import a archive file to the specified project.
RundeckJobsImportResult	importJobs(String filename, RundeckJobsImport rundeckJobsImport) Import the definitions of jobs, from the given input stream, using the given behavior
RundeckJobsImportResult	importJobs(RundeckJobsImport rundeckJobsImport) Import the definitions of jobs, from the given input stream, using the given behavior
List<RundeckToken>	listApiTokens() List all API tokens
List<RundeckToken>	listApiTokens(String user) List API tokens for a user.
List<KeyResource>	listKeyDirectory(String path) List contents of key directory
List<KeyResource>	listKeyDirectoryRoot() List contents of root key directory
void	ping() Try to "ping" the Rundeck instance to see if it is alive
String	readProjectFile(String projectName, String filename) Read contents of a project readme.md or motd.md if it exsts, or return null
RundeckExecution	runAdhocCommand(RunAdhocCommand command) Run an ad-hoc command, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runAdhocCommand(RunAdhocCommand command, long poolingInterval, TimeUnit poolingUnit) Run an ad-hoc command, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runAdhocScript(RunAdhocScript script) Run an ad-hoc script, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runAdhocScript(RunAdhocScript script, String scriptFilename, long poolingInterval, TimeUnit poolingUnit) Run an ad-hoc script read from a file, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runAdhocScript(RunAdhocScript script, long poolingInterval, TimeUnit poolingUnit) Run an ad-hoc script, and wait until its execution is finished (or aborted) to return.
RundeckExecution	runJob(RunJob runJob) Run a Rundeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return.
RundeckExecution	runJob(RunJob jobRun, long poolingInterval, TimeUnit poolingUnit) Run a Rundeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return.
String	setProjectConfig(String projectName, String key, String value) Set a single project configuration property value
ProjectConfig	setProjectConfig(String projectName, Map<String, String> configuration) Return the configuration of a project
KeyResource	storeKey(String path, File keyfile, boolean privateKey) Store an key file
void	storeProjectFile(String projectName, String filename, String content) Store contents to a project readme.md or motd.md
String	testAuth() Test the authentication on the Rundeck instance.
String	toString()
RundeckExecution	triggerAdhocCommand(RunAdhocCommand command) Trigger the execution of an ad-hoc command, and return immediately (without waiting the end of the execution).
RundeckExecution	triggerAdhocScript(RunAdhocScript script) Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution).
RundeckExecution	triggerAdhocScript(RunAdhocScript script, String scriptFilename) Trigger the execution of an ad-hoc script read from a file, and return immediately (without waiting the end of the execution).
RundeckExecution	triggerJob(RunJob jobRun) Trigger the execution of a Rundeck job (identified by the given ID), and return immediately (without waiting the end of the job execution)

[Expand]

Inherited Methods

From class java.lang.Object

Constants

public static final String API_ENDPOINT

End-point of the API

public static final int API_VERSION

Version of the API supported

public static final long DEFAULT_POOLING_INTERVAL

Default value for the "pooling interval" used when running jobs/commands/scripts

Constant Value: 5 (0x0000000000000005)

public static final TimeUnit DEFAULT_POOLING_UNIT

Default unit of the "pooling interval" used when running jobs/commands/scripts

public static final String JOBS_IMPORT

Constant Value: "/jobs/import"

public static final String STORAGE_KEYS_PATH

Constant Value: "keys/"

public static final String STORAGE_ROOT_PATH

Constant Value: "/storage/"

Public Methods

public RundeckAbort abortExecution (Long executionId)

Abort an execution (identified by the given ID). The execution should be running...

Parameters

executionId	identifier of the execution - mandatory

Returns

a RundeckAbort instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent execution with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the executionId is null

public RundeckAbort abortExecution (Long executionId, String asUser)

Abort an execution (identified by the given ID). The execution should be running...

Parameters

executionId	identifier of the execution - mandatory
asUser	specify a user name to abort the job as, must have 'killAs' permission

Returns

a RundeckAbort instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent execution with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the executionId is null

public static RundeckClientBuilder builder ()

Create a builder for RundeckClient

public RundeckProject createProject (String projectName, Map<String, String> configuration)

Create a new project, and return the new definition

Parameters

projectName	name of the project - mandatory
configuration	project configuration properties

Returns

a RundeckProject instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)

public DeleteExecutionsResponse deleteAllJobExecutions (String jobId)

Delete all executions for a job specified by a job ID

Parameters

jobId	Identifier for the job

Returns

a DeleteExecutionsResponse instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent execution with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the executionIds is null

public boolean deleteApiToken (String token)

Delete an existing token@return

Throws

RundeckApiException

public void deleteExecution (Long executionId)

Delete a single execution, identified by the given ID

Parameters

executionId	identifier for the execution - mandatory

Throws

RundeckApiException	in case of error when calling the API (non-existent execution with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the executionId is null

public DeleteExecutionsResponse deleteExecutions (Set<Long> executionIds)

Delete a set of executions, identified by the given IDs

Parameters

executionIds	set of identifiers for the executions - mandatory

Returns

a DeleteExecutionsResponse instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent execution with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the executionIds is null

public String deleteJob (String jobId)

Delete a single job, identified by the given ID

Parameters

jobId	identifier of the job - mandatory

Returns

the success message (note that in case of error, you'll get an exception)

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public RundeckJobDeleteBulk deleteJobs (List<String> jobIds)

Delete multiple jobs, identified by the given IDs

Parameters

jobIds	List of job IDS

Returns

the bulk delete result

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public void deleteKey (String path)

Delete an key file

Parameters

path	a path to a key file, must start with "keys/"

public void deleteProject (String projectName)

Delete a project

Parameters

projectName	name of the project - mandatory

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)

public void deleteProjectConfig (String projectName, String key)

Set a single project configuration property value

Parameters

projectName	name of the project - mandatory
key	name of the configuration property

Returns

new value

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)

public void deleteProjectFile (String projectName, String filename)

Delete a project readme.md or motd.md

Parameters

projectName	project name
filename	filename, must be readme.md or motd.md

public boolean equals (Object obj)

public InputStream exportJob (String format, String jobId)

Export the definition of a single job, identified by the given ID

Parameters

format	of the export. See `FileType` - mandatory
jobId	identifier of the job - mandatory

Returns

an InputStream instance, not linked to any network resources - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the format or jobId is blank (null, empty or whitespace), or the format is invalid

public InputStream exportJob (FileType format, String jobId)

Export the definition of a single job, identified by the given ID

Parameters

format	of the export. See `FileType` - mandatory
jobId	identifier of the job - mandatory

Returns

an InputStream instance, not linked to any network resources - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace), or the format is null

public void exportJobToFile (String filename, String format, String jobId)

Export the definition of a single job (identified by the given ID)

Parameters

filename	path of the file where the content should be saved - mandatory
format	of the export. See `FileType` - mandatory
jobId	identifier of the job - mandatory

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the filename, format or jobId is blank (null, empty or whitespace), or the format is invalid
IOException	if we failed to write to the file

public void exportJobToFile (String filename, FileType format, String jobId)

Export the definition of a single job (identified by the given ID)

Parameters

filename	path of the file where the content should be saved - mandatory
format	of the export. See `FileType` - mandatory
jobId	identifier of the job - mandatory

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the filename or jobId is blank (null, empty or whitespace), or the format is null
IOException	if we failed to write to the file

public InputStream exportJobs (String format, String project)

Export the definitions of all jobs that belongs to the given project

Parameters

format	of the export. See `FileType` - mandatory
project	name of the project - mandatory

Returns

an InputStream instance, not linked to any network resources - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the format or project is blank (null, empty or whitespace), or the format is invalid

public InputStream exportJobs (String format, String project, String jobFilter, String groupPath, String... jobIds)

Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)

Parameters

format	of the export. See `FileType` - mandatory
project	name of the project - mandatory
jobFilter	a filter for the job Name - optional
groupPath	a group or partial group path to include all jobs within that group path - optional
jobIds	a list of Job IDs to include - optional

Returns

an InputStream instance, not linked to any network resources - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the format or project is blank (null, empty or whitespace), or the format is invalid

public InputStream exportJobs (FileType format, String project)

Export the definitions of all jobs that belongs to the given project

Parameters

format	of the export. See `FileType` - mandatory
project	name of the project - mandatory

Returns

an InputStream instance, not linked to any network resources - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace) or the format is null

public InputStream exportJobs (FileType format, String project, String jobFilter, String groupPath, String... jobIds)

Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)

Parameters

format	of the export. See `FileType` - mandatory
project	name of the project - mandatory
jobFilter	a filter for the job Name - optional
groupPath	a group or partial group path to include all jobs within that group path - optional
jobIds	a list of Job IDs to include - optional

Returns

an InputStream instance, not linked to any network resources - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace) or the format is null

public void exportJobsToFile (String filename, String format, String project)

Export the definitions of all jobs that belongs to the given project

Parameters

filename	path of the file where the content should be saved - mandatory
format	of the export. See `FileType` - mandatory
project	name of the project - mandatory

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the format or project is blank (null, empty or whitespace), or the format is invalid
IOException	if we failed to write to the file

public void exportJobsToFile (String filename, String format, String project, String jobFilter, String groupPath, String... jobIds)

Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)

Parameters

filename	path of the file where the content should be saved - mandatory
format	of the export. See `FileType` - mandatory
project	name of the project - mandatory
jobFilter	a filter for the job Name - optional
groupPath	a group or partial group path to include all jobs within that group path - optional
jobIds	a list of Job IDs to include - optional

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the filename, format or project is blank (null, empty or whitespace), or the format is invalid
IOException	if we failed to write to the file

public void exportJobsToFile (String filename, FileType format, String project)

Export the definitions of all jobs that belongs to the given project

Parameters

filename	path of the file where the content should be saved - mandatory
format	of the export. See `FileType` - mandatory
project	name of the project - mandatory

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace) or the format is null
IOException	if we failed to write to the file

public void exportJobsToFile (String filename, FileType format, String project, String jobFilter, String groupPath, String... jobIds)

Export the definitions of the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)

Parameters

filename	path of the file where the content should be saved - mandatory
format	of the export. See `FileType` - mandatory
project	name of the project - mandatory
jobFilter	a filter for the job Name - optional
groupPath	a group or partial group path to include all jobs within that group path - optional
jobIds	a list of Job IDs to include - optional

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the filename or project is blank (null, empty or whitespace), or the format is null
IOException	if we failed to write to the file

public int exportProject (String projectName, File out)

Convenience method to export the archive of a project to the specified file.

Parameters

projectName	name of the project - mandatory
out	file to write to

Returns

number of bytes written to the stream

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)
IOException

public int exportProject (String projectName, OutputStream out)

Export the archive of a project to the specified outputstream

Parameters

projectName	name of the project - mandatory

Returns

number of bytes written to the stream

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)
IOException

public RundeckJob findJob (String project, String groupPath, String name)

Find a job, identified by its project, group and name. Note that the groupPath is optional, as a job does not need to belong to a group (either pass null, or an empty string).

Parameters

project	name of the project - mandatory
groupPath	group to which the job belongs (if it belongs to a group) - optional
name	of the job to find - mandatory

Returns

a RundeckJob instance - null if not found

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project or the name is blank (null, empty or whitespace)

public String generateApiToken (String user)

Generate an API token for a user.@return

Throws

RundeckApiException

public InputStream generateToken (String username)

Generate a new token and get the result page (which is the html page of the user's profile)

Parameters

username	- mandatory

Returns

an InputStream instance, not linked to any network resources - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent name or project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the name or project is blank (null, empty or whitespace)

public RundeckToken getApiToken (String token)

Return user info for an existing token

Returns

token info

Throws

RundeckApiException

public RundeckExecution getExecution (Long executionId)

Get a single execution, identified by the given ID

Parameters

executionId	identifier of the execution - mandatory

Returns

a RundeckExecution instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent execution with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the executionId is null

public RundeckOutput getExecutionOutput (Long executionId, int offset, int lastlines, long lastmod, int maxlines)

Get the execution output of the given job

Parameters

executionId	identifier of the execution - mandatory
offset	byte offset to read from in the file. 0 indicates the beginning.
lastlines	nnumber of lines to retrieve from the end of the available output. If specified it will override the offset value and return only the specified number of lines at the end of the log.
lastmod	epoch datestamp in milliseconds, return results only if modification changed since the specified date OR if more data is available at the given offset
maxlines	maximum number of lines to retrieve forward from the specified offset.

Returns

RundeckOutput

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public RundeckOutput getExecutionOutput (Long executionId, int offset, long lastmod, int maxlines)

Get the execution output of the given job

Parameters

executionId	identifier of the execution - mandatory
offset	byte offset to read from in the file. 0 indicates the beginning.
lastmod	epoch datestamp in milliseconds, return results only if modification changed since the specified date OR if more data is available at the given offset
maxlines	maximum number of lines to retrieve forward from the specified offset.

Returns

RundeckOutput

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public RundeckOutput getExecutionOutputForNode (Long executionId, String nodeName, int offset, int lastlines, long lastmod, int maxlines)

Get the execution output of the given execution on the specified node

Parameters

executionId	identifier of the execution - mandatory
nodeName	name of the node
offset	byte offset to read from in the file. 0 indicates the beginning.
lastlines	nnumber of lines to retrieve from the end of the available output. If specified it will override the offset value and return only the specified number of lines at the end of the log.
lastmod	epoch datestamp in milliseconds, return results only if modification changed since the specified date OR if more data is available at the given offset
maxlines	maximum number of lines to retrieve forward from the specified offset.

Returns

RundeckOutput

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public RundeckOutput getExecutionOutputForNodeAndStep (Long executionId, String nodeName, String stepCtx, int offset, int lastlines, long lastmod, int maxlines)

Get the execution output of the given execution for the specified step

Parameters

executionId	identifier of the execution - mandatory
stepCtx	identifier for the step
offset	byte offset to read from in the file. 0 indicates the beginning.
lastlines	nnumber of lines to retrieve from the end of the available output. If specified it will override the offset value and return only the specified number of lines at the end of the log.
lastmod	epoch datestamp in milliseconds, return results only if modification changed since the specified date OR if more data is available at the given offset
maxlines	maximum number of lines to retrieve forward from the specified offset.

Returns

RundeckOutput

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public RundeckOutput getExecutionOutputForStep (Long executionId, String stepCtx, int offset, int lastlines, long lastmod, int maxlines)

Get the execution output of the given execution for the specified step

Parameters

executionId	identifier of the execution - mandatory
stepCtx	identifier for the step
offset	byte offset to read from in the file. 0 indicates the beginning.
lastlines	nnumber of lines to retrieve from the end of the available output. If specified it will override the offset value and return only the specified number of lines at the end of the log.
lastmod	epoch datestamp in milliseconds, return results only if modification changed since the specified date OR if more data is available at the given offset
maxlines	maximum number of lines to retrieve forward from the specified offset.

Returns

RundeckOutput

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public RundeckOutput getExecutionOutputState (Long executionId, boolean stateOnly, int offset, long lastmod, int maxlines)

Get the execution state output sequence of the given job

Parameters

executionId	identifier of the execution - mandatory
stateOnly	if true, include only state change output entries, otherwise include state and log entries
offset	byte offset to read from in the file. 0 indicates the beginning.
lastmod	epoch datestamp in milliseconds, return results only if modification changed since the specified date OR if more data is available at the given offset
maxlines	maximum number of lines to retrieve forward from the specified offset.

Returns

RundeckOutput

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public RundeckExecutionState getExecutionState (Long executionId)

Get the execution state of the given execution

Parameters

executionId	identifier of the execution - mandatory

Returns

RundeckExecutionState the execution state

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public PagedResults<RundeckExecution> getExecutions (ExecutionQuery query, Long max, Long offset)

Get executions based on query parameters

Parameters

query	query parameters for the request
max	number of results to return - optional (null for all)
offset	the 0-indexed offset for the first result to return - optional

Returns

a List of RundeckExecution : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project, Long max, Long offset)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory
max	number of results to return - optional (default to 20)
offset	the 0-indexed offset for the first result to return - optional (default to O)

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project, String recent)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory
recent	include only events matching the given period of time. Format : "XY", where X is an integer, and Y is one of : "h" (hour), "d" (day), "w" (week), "m" (month), "y" (year). Example : "2w" (= last 2 weeks), "5d" (= last 5 days), etc. Optional.

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project, String recent, Long max, Long offset)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory
recent	include only events matching the given period of time. Format : "XY", where X is an integer, and Y is one of : "h" (hour), "d" (day), "w" (week), "m" (month), "y" (year). Example : "2w" (= last 2 weeks), "5d" (= last 5 days), etc. Optional.
max	number of results to return - optional (default to 20)
offset	the 0-indexed offset for the first result to return - optional (default to O)

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project, String jobId, String reportId, String user)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory
jobId	include only events matching the given job ID - optional
reportId	include only events matching the given report ID - optional
user	include only events created by the given user - optional

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project, String jobId, String reportId, String user, Long max, Long offset)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory
jobId	include only events matching the given job ID - optional
reportId	include only events matching the given report ID - optional
user	include only events created by the given user - optional
max	number of results to return - optional (default to 20)
offset	the 0-indexed offset for the first result to return - optional (default to O)

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project, String jobId, String reportId, String user, String recent, Date begin, Date end, Long max, Long offset)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory
jobId	include only events matching the given job ID - optional
reportId	include only events matching the given report ID - optional
user	include only events created by the given user - optional
recent	include only events matching the given period of time. Format : "XY", where X is an integer, and Y is one of : "h" (hour), "d" (day), "w" (week), "m" (month), "y" (year). Example : "2w" (= last 2 weeks), "5d" (= last 5 days), etc. Optional.
begin	date for the earlier events to retrieve - optional
end	date for the latest events to retrieve - optional
max	number of results to return - optional (default to 20)
offset	the 0-indexed offset for the first result to return - optional (default to O)

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project, String user, String recent, List<String> includeJobNames, List<String> excludeJobNames, Date begin, Date end, Long max, Long offset)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory
user	include only events created by the given user - optional
recent	include only events matching the given period of time. Format : "XY", where X is an integer, and Y is one of : "h" (hour), "d" (day), "w" (week), "m" (month), "y" (year). Example : "2w" (= last 2 weeks), "5d" (= last 5 days), etc. Optional.
includeJobNames	list of job names ("group/name") to include results for
excludeJobNames	list of job names ("group/name") to exclude results for
begin	date for the earlier events to retrieve - optional
end	date for the latest events to retrieve - optional
max	number of results to return - optional (default to 20)
offset	the 0-indexed offset for the first result to return - optional (default to O)

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project, Date begin, Date end)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory
begin	date for the earlier events to retrieve - optional
end	date for the latest events to retrieve - optional

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckHistory getHistory (String project, Date begin, Date end, Long max, Long offset)

Get the (events) history for the given project

Parameters

project	name of the project - mandatory
begin	date for the earlier events to retrieve - optional
end	date for the latest events to retrieve - optional
max	number of results to return - optional (default to 20)
offset	the 0-indexed offset for the first result to return - optional (default to O)

Returns

a RundeckHistory instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public RundeckJob getJob (String jobId)

Get the definition of a single job, identified by the given ID

Parameters

jobId	identifier of the job - mandatory

Returns

a RundeckJob instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public List<RundeckExecution> getJobExecutions (String jobId)

Get the executions of the given job

Parameters

jobId	identifier of the job - mandatory

Returns

a List of RundeckExecution : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public List<RundeckExecution> getJobExecutions (String jobId, String status)

Get the executions of the given job

Parameters

jobId	identifier of the job - mandatory
status	of the executions, see `RundeckExecution.ExecutionStatus` - optional (null for all)

Returns

a List of RundeckExecution : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace), or the executionStatus is invalid

public List<RundeckExecution> getJobExecutions (String jobId, String status, Long max, Long offset)

Get the executions of the given job

Parameters

jobId	identifier of the job - mandatory
status	of the executions, see `RundeckExecution.ExecutionStatus` - optional (null for all)
max	number of results to return - optional (null for all)
offset	the 0-indexed offset for the first result to return - optional

Returns

a List of RundeckExecution : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace), or the executionStatus is invalid

public List<RundeckExecution> getJobExecutions (String jobId, RundeckExecution.ExecutionStatus status)

Get the executions of the given job

Parameters

jobId	identifier of the job - mandatory
status	of the executions, see `RundeckExecution.ExecutionStatus` - optional (null for all)

Returns

a List of RundeckExecution : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public List<RundeckExecution> getJobExecutions (String jobId, RundeckExecution.ExecutionStatus status, Long max, Long offset)

Get the executions of the given job

Parameters

jobId	identifier of the job - mandatory
status	of the executions, see `RundeckExecution.ExecutionStatus` - optional (null for all)
max	number of results to return - optional (null for all)
offset	the 0-indexed offset for the first result to return - optional

Returns

a List of RundeckExecution : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public List<RundeckJob> getJobs ()

List all jobs (for all projects)

Returns

a List of RundeckJob : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)

public List<RundeckJob> getJobs (String project)

List all jobs that belongs to the given project

Parameters

project	name of the project - mandatory

Returns

a List of RundeckJob : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public List<RundeckJob> getJobs (String project, String jobFilter, String groupPath, String... jobIds)

List the jobs that belongs to the given project, and matches the given criteria (jobFilter, groupPath and jobIds)

Parameters

project	name of the project - mandatory
jobFilter	a filter for the job Name - optional
groupPath	a group or partial group path to include all jobs within that group path - optional
jobIds	a list of Job IDs to include - optional

Returns

a List of RundeckJob : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public KeyResource getKey (String path)

Get metadata for an key file

Parameters

path	ssh key storage path, must start with "keys/"

Returns

the ssh key resource

Throws

RundeckApiException	if there is an error, or if the path is a directory not a file

public String getLogin ()

Returns

the login used for authentication on the Rundeck instance (null if using token-based or session-based auth)

public RundeckNode getNode (String name, String project)

Get the definition of a single node

Parameters

name	of the node - mandatory
project	name of the project - mandatory

Returns

a RundeckNode instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent name or project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the name or project is blank (null, empty or whitespace)

public List<RundeckNode> getNodes ()

List all nodes (for all projects)

Returns

a List of RundeckNode : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)

public List<RundeckNode> getNodes (String project)

List all nodes that belongs to the given project

Parameters

project	name of the project - mandatory

Returns

a List of RundeckNode : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public List<RundeckNode> getNodes (String project, Properties nodeFilters)

List nodes that belongs to the given project

Parameters

project	name of the project - mandatory
nodeFilters	for filtering the nodes - optional. See `NodeFiltersBuilder`

Returns

a List of RundeckNode : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public InputStream getOutput (String executionId)

Get the output of a job execution

Parameters

executionId	id of the execution - mandatory

Returns

an InputStream instance, not linked to any network resources - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent name or project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the name or project is blank (null, empty or whitespace)

public String getPassword ()

Returns

the password used for authentication on the Rundeck instance (null if using token-based or session-based auth)

public InputStream getProfilePage (String username)

Get the html page of the user's profile

Parameters

username	- mandatory

Returns

an InputStream instance, not linked to any network resources - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent name or project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the name or project is blank (null, empty or whitespace)

public RundeckProject getProject (String projectName)

Get the definition of a single project, identified by the given name

Parameters

projectName	name of the project - mandatory

Returns

a RundeckProject instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)

public ProjectConfig getProjectConfig (String projectName)

Return the configuration of a project

Parameters

projectName	name of the project - mandatory

Returns

a ProjectConfig instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)

public String getProjectConfig (String projectName, String key)

Get a single project configuration key

Parameters

projectName	name of the project - mandatory
key	name of the configuration key

Returns

value, or null if the value is not set

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)

public List<RundeckProject> getProjects ()

List all projects

Returns

a List of RundeckProject : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)

public int getPublicKeyContent (String path, File out)

Get content for a public key file

Parameters

path	ssh key storage path, must start with "keys/"
out	file to write data to

Returns

length of written data

Throws

RundeckApiException
IOException

public int getPublicKeyContent (String path, OutputStream out)

Get content for a public key file

Parameters

path	ssh key storage path, must start with "keys/"
out	outputstream to write data to

Returns

length of written data

Throws

RundeckApiException
IOException

public List<RundeckExecution> getRunningExecutions ()

Get all running executions (for all projects)

Returns

a List of RundeckExecution : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)

public List<RundeckExecution> getRunningExecutions (String project)

Get the running executions for the given project

Parameters

project	name of the project - mandatory

Returns

a List of RundeckExecution : might be empty, but won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace)

public String getSessionID ()

Returns

the sessionID used for authentication on the Rundeck instance (null if using login-based or token-based auth)

public RundeckSystemInfo getSystemInfo ()

Get system informations about the Rundeck server

Returns

a RundeckSystemInfo instance - won't be null

Throws

RundeckApiException	in case of error when calling the API
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)

public String getToken ()

Returns

the auth-token used for authentication on the Rundeck instance (null if using login-based or session-based auth)

public String getUrl ()

Returns

the URL of the Rundeck instance ("http://localhost:4440", "http://rundeck.your-compagny.com/", etc)

public int hashCode ()

public ArchiveImport importArchive (String projectName, File archiveFile, boolean includeExecutions, boolean preserveJobUuids)

Import a archive file to the specified project.

Parameters

projectName	name of the project - mandatory
archiveFile	zip archive file
includeExecutions	if true, import executions defined in the archive, otherwise skip them
preserveJobUuids	if true, do not remove UUIDs from imported jobs, otherwise remove them

Returns

Result of the import request, may contain a list of import error messages

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)
IOException

public RundeckJobsImportResult importJobs (String filename, RundeckJobsImport rundeckJobsImport)

Import the definitions of jobs, from the given input stream, using the given behavior

Parameters

rundeckJobsImport	import request, see `RundeckJobsImportBuilder`

Returns

a RundeckJobsImportResult instance - won't be null

Throws

RundeckApiException	in case of error when calling the API
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the stream or fileType is null
IOException

public RundeckJobsImportResult importJobs (RundeckJobsImport rundeckJobsImport)

Import the definitions of jobs, from the given input stream, using the given behavior

Parameters

rundeckJobsImport	import request, see `RundeckJobsImportBuilder`

Returns

a RundeckJobsImportResult instance - won't be null

Throws

RundeckApiException	in case of error when calling the API
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the stream or fileType is null

public List<RundeckToken> listApiTokens ()

List all API tokens

Returns

list of tokens

Throws

RundeckApiException

public List<RundeckToken> listApiTokens (String user)

List API tokens for a user.

Parameters

user	username

Returns

list of tokens

Throws

RundeckApiException

public List<KeyResource> listKeyDirectory (String path)

List contents of key directory

Parameters

path	ssh key storage path, must start with "keys/"

Throws

RundeckApiException	if there is an error, or if the path is a file not a directory

public List<KeyResource> listKeyDirectoryRoot ()

List contents of root key directory

Returns

list of key resources

Throws

RundeckApiException

public void ping ()

Try to "ping" the Rundeck instance to see if it is alive

Throws

RundeckApiException	if the ping fails

public String readProjectFile (String projectName, String filename)

Read contents of a project readme.md or motd.md if it exsts, or return null

Parameters

projectName	project name
filename	filename, must be readme.md or motd.md

Returns

contents, or null

public RundeckExecution runAdhocCommand (RunAdhocCommand command)

Run an ad-hoc command, and wait until its execution is finished (or aborted) to return. We will poll the Rundeck server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still running. The command will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters

command	the RunAdhocCommand, see `RunAdhocCommandBuilder`

Returns

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project or command is blank (null, empty or whitespace)

public RundeckExecution runAdhocCommand (RunAdhocCommand command, long poolingInterval, TimeUnit poolingUnit)

Run an ad-hoc command, and wait until its execution is finished (or aborted) to return. We will poll the Rundeck server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is finished (or aborted) or is still running. The command will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters

command	the RunAdhocCommand, see `RunAdhocCommandBuilder`
poolingInterval	for checking the status of the execution. Must be > 0.
poolingUnit	unit (seconds, milli-seconds, ...) of the interval. Default to seconds.

Returns

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project or command is blank (null, empty or whitespace)

public RundeckExecution runAdhocScript (RunAdhocScript script)

Run an ad-hoc script, and wait until its execution is finished (or aborted) to return. We will poll the Rundeck server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still running. The script will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters

script	the RunAdhocScript, see `RunAdhocScriptBuilder`

Returns

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace) or the script is null
IOException	if we failed to read the file

public RundeckExecution runAdhocScript (RunAdhocScript script, String scriptFilename, long poolingInterval, TimeUnit poolingUnit)

Run an ad-hoc script read from a file, and wait until its execution is finished (or aborted) to return. We will poll the Rundeck server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is finished (or aborted) or is still running. The script will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters

script	the RunAdhocScript, see `RunAdhocScriptBuilder`
scriptFilename	filename of a script to read
poolingInterval	for checking the status of the execution. Must be > 0.
poolingUnit	unit (seconds, milli-seconds, ...) of the interval. Default to seconds.

Returns

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace) or the script is null
IOException	if we failed to read the file

public RundeckExecution runAdhocScript (RunAdhocScript script, long poolingInterval, TimeUnit poolingUnit)

Run an ad-hoc script, and wait until its execution is finished (or aborted) to return. We will poll the Rundeck server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is finished (or aborted) or is still running. The script will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters

script	the RunAdhocScript, see `RunAdhocScriptBuilder`
poolingInterval	for checking the status of the execution. Must be > 0.
poolingUnit	unit (seconds, milli-seconds, ...) of the interval. Default to seconds.

Returns

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace) or the script is null
IOException	if we failed to read the file

public RundeckExecution runJob (RunJob runJob)

Run a Rundeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return. We will poll the Rundeck server at regular interval (every 5 seconds) to know if the execution is finished (or aborted) or is still running.

Parameters

runJob	the RunJob, see `RunJobBuilder`

Returns

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public RundeckExecution runJob (RunJob jobRun, long poolingInterval, TimeUnit poolingUnit)

Run a Rundeck job (identified by the given ID), and wait until its execution is finished (or aborted) to return. We will poll the Rundeck server at regular interval (configured by the poolingInterval/poolingUnit couple) to know if the execution is finished (or aborted) or is still running.

Parameters

jobRun	the RunJob, see `RunJobBuilder`
poolingInterval	for checking the status of the execution. Must be > 0.
poolingUnit	unit (seconds, milli-seconds, ...) of the interval. Default to seconds.

Returns

a RundeckExecution instance for the (finished/aborted) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

public String setProjectConfig (String projectName, String key, String value)

Set a single project configuration property value

Parameters

projectName	name of the project - mandatory
key	name of the configuration property
value	value of the property

Returns

new value

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)

public ProjectConfig setProjectConfig (String projectName, Map<String, String> configuration)

Return the configuration of a project

Parameters

projectName	name of the project - mandatory

Returns

a ProjectConfig instance - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the projectName is blank (null, empty or whitespace)

public KeyResource storeKey (String path, File keyfile, boolean privateKey)

Store an key file

Parameters

path	ssh key storage path, must start with "keys/"
keyfile	key file
privateKey	true to store private key, false to store public key

Returns

the key resource

Throws

RundeckApiException

public void storeProjectFile (String projectName, String filename, String content)

Store contents to a project readme.md or motd.md

Parameters

projectName	project name
filename	filename, must be readme.md or motd.md
content	content

public String testAuth ()

Test the authentication on the Rundeck instance.

Returns

sessionID if doing username+password login and it succeeded

Throws

RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)

public String toString ()

public RundeckExecution triggerAdhocCommand (RunAdhocCommand command)

Trigger the execution of an ad-hoc command, and return immediately (without waiting the end of the execution). The command will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters

command	the RunAdhocCommand. Project and command are mandatory, see `RunAdhocCommandBuilder`

Returns

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project or command is blank (null, empty or whitespace)

public RundeckExecution triggerAdhocScript (RunAdhocScript script)

Trigger the execution of an ad-hoc script, and return immediately (without waiting the end of the execution). The script will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters

script	the RunAdhocScript, see `RunAdhocScriptBuilder`

Returns

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace) or the script is null

public RundeckExecution triggerAdhocScript (RunAdhocScript script, String scriptFilename)

Trigger the execution of an ad-hoc script read from a file, and return immediately (without waiting the end of the execution). The script will be dispatched to nodes, accordingly to the nodeFilters parameter.

Parameters

script	the RunAdhocScript, see `RunAdhocScriptBuilder`
scriptFilename	a file to read as the input script stream

Returns

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent project with this name)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the project is blank (null, empty or whitespace) or the script is null
IOException	if an error occurs reading the script file

public RundeckExecution triggerJob (RunJob jobRun)

Trigger the execution of a Rundeck job (identified by the given ID), and return immediately (without waiting the end of the job execution)

Parameters

jobRun	the RunJob, see `RunJobBuilder`

Returns

a RundeckExecution instance for the newly created (and running) execution - won't be null

Throws

RundeckApiException	in case of error when calling the API (non-existent job with this ID)
RundeckApiException.RundeckApiLoginException	if the login fails (in case of login-based authentication)
RundeckApiException.RundeckApiTokenException	if the token is invalid (in case of token-based authentication)
IllegalArgumentException	if the jobId is blank (null, empty or whitespace)

Interfaces

Classes

Enums

Exceptions

RundeckClient

Class Overview

Summary

Constants

public static final String API_ENDPOINT

public static final int API_VERSION

public static final long DEFAULT_POOLING_INTERVAL

public static final TimeUnit DEFAULT_POOLING_UNIT

public static final String JOBS_IMPORT

public static final String STORAGE_KEYS_PATH

public static final String STORAGE_ROOT_PATH

Public Methods

public RundeckAbort abortExecution (Long executionId)

Parameters

Returns

Throws

public RundeckAbort abortExecution (Long executionId, String asUser)

Parameters

Returns

Throws

public static RundeckClientBuilder builder ()

public RundeckProject createProject (String projectName, Map<String, String> configuration)

Parameters

Returns

Throws

public DeleteExecutionsResponse deleteAllJobExecutions (String jobId)

Parameters

Returns

Throws

public boolean deleteApiToken (String token)

Throws

public void deleteExecution (Long executionId)

Parameters

Throws

public DeleteExecutionsResponse deleteExecutions (Set<Long> executionIds)

Parameters

Returns

Throws

public String deleteJob (String jobId)

Parameters

Returns

Throws

public RundeckJobDeleteBulk deleteJobs (List<String> jobIds)

Parameters

Returns

Throws

public void deleteKey (String path)

Parameters

public void deleteProject (String projectName)

Parameters

Throws

public void deleteProjectConfig (String projectName, String key)

Parameters

Returns

Throws

public void deleteProjectFile (String projectName, String filename)

Parameters

public boolean equals (Object obj)

public InputStream exportJob (String format, String jobId)

Parameters

Returns

Throws

See Also

public InputStream exportJob (FileType format, String jobId)

Parameters

Returns

Throws

See Also

public void exportJobToFile (String filename, String format, String jobId)

Parameters

Throws

See Also

public void exportJobToFile (String filename, FileType format, String jobId)

Parameters

Throws

See Also