Jump to content
JasperReports Library 7.0 is now available ×
  • This documentation is an older version of JasperReports Server REST API Reference. View the latest documentation.

    The rest_v2/jobs service provides the interface to schedule reports and manage scheduled reports (also called jobs). This service provides an API to scheduler features that were introduced in JasperReports Server 4.7, such as bulk updates, pausing jobs, FTP output and exclusion calendars.

    This chapter includes the following sections:

    Listing Report Jobs
    Extended Job Search
    Viewing a Job Definition
    Scheduling a Report
    Viewing Job Status
    Editing a Job Definition
    Updating Jobs in Bulk
    Pausing Jobs
    Resuming Jobs
    Restarting Failed Jobs
    Deleting Jobs
    Specifying FTP Output
    Specifying File System Output

    Listing Report Jobs

    Use the following method to list jobs, either all jobs managed by the scheduler or the jobs for a specific report:

    Method

    URL

    GET

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs

    Argument

    Type/Value

    Description

    reportUnitURI?

    /path/to/report

    Optional URI of a report or report option to list all of its jobs. When specified, the results are only for the specified report or report option.

    Options

    accept: application/xml

    accept: application/json

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The body contains and array or list of jobsummary descriptors.

    404 Not Found – When no job is found.

    The jobs are described in a jobsummary element such as the following example:

    note-icon-ns_28x28.png.1136d185e0e844d013f47e2c6751ae0a.png

    The jobsummary XML element returned by the rest_v2/jobs service has a different structure than the element with the same name returned by the deprecated rest/jobsummary (v1) service.

    Extended Job Search

    The GET method is also used for more advanced job searches. You can search by owner or for strings in the label, or you can match arbitrary fields of the job descriptor with a special syntax. You can also control the pagination and sorting order of the reply.

    Method

    URL

    GET

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?<arguments>

    Argument

    Type/Value

    Description

    label

    string

    Performs a case-insensitive string search for this value anywhere within the label field of every job.

    owner

    string

    The name of the user who scheduled the report, if necessary in the format <username>%7C<organization> (%7C is the |character).

    reportUnitURI?

    /path/to/report

    Specify the URI of a report or report option to list all of its jobs.

    example?

    JSON jobModel

    Searches for jobs that match the JSON jobModel, which is a fragment of a job descriptor containing one or more fields to be matched. Because the JSON fragment appears as an argument to the URL, it must be properly URL-encoded (percent-encoded). See the example below.

    limit

    integer

    Turns on pagination of the result by specifying the number of jobsummary descriptors per results page. The default is -1 for no limit and thus no pagination (all results are returned together).

    offset

    integer

    Determines the page number in paginated results by specifying the index of the first jobsummary to be returned.

    sortType

     

    Possible values are: NONE, SORTBY_JOBID, SORTBY_JOBNAME, SORTBY_REPORTURI, SORTBY_REPORTNAME, SORTBY_REPORTFOLDER, SORTBY_OWNER, SORTBY_STATUS, SORTBY_LASTRUN, SORTBY_NEXTRUN

    isAscending

    true / false

    Determines the sort order: ascending if true, descending if false or omitted.

    Options

    accept: application/xml

    accept: application/json

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The body contains and array or list of jobsummary descriptors that match the search criteria.

    404 Not Found – When no matching job is found in the server.

    The body of the response contains jobsummary elements, in the same format as shown in Listing Report Jobs.

    The example parameter lets you specify a search on fields in the job descriptor, such as output formats. You can specify any field in the job descriptor or in any of its nested structures. Some fields may be specified in both the example parameter and in a dedicated parameter, for example label. In that case, the search specified in the example parameter takes precedence.

    For example, you can search for all jobs that specify an output format of PDF. The JSON jobModel to specify this field is:

    {"outputFormat":"PDF"}

    And the corresponding URI, with proper encoding, is:

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?example=

    %7b%22outputFormat%22%3a%22PDF%22%7d

    Viewing a Job Definition

    Once you search for and find the ID of a job, use the GET method with that specific job ID to retrieve its detailed information.

    Method

    URL

    GET

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/

    Options

    accept: application/job+xml

    accept: application/job+json

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The body contains a descriptor with all details about the job.

    404 Not Found – When the specified job is not found in the server.

    The GET method returns a descriptor that fully describes all the aspects of a scheduled job, such as recurrence, parameters, output, email notifications, and alerts, if any. For additional options around file output, see Specifying FTP Output and Specifying File System Output.

    JSON:

    XML:

    Scheduling a Report

    To schedule a report, create its job descriptor similar to the one returned by the GET method, and use the PUT method of the jobs service. Specify the report being scheduled inside the job descriptor. You do not need to specify any job IDs in the descriptor, because the server will assign them.

    Method

    URL

    PUT

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/

    Content-Type

    Content

    application/job+xml

    application/job+json

    A well-formed XML or JSON job descriptor as described.

    Options

    accept: application/job+xml

    accept: application/job+json

    Return Value on Success

    Typical Return Values on Failure

    201 Created – The body contains the job descriptor of the newly created job. It is similar to the one that was sent but now contains the jobID for the new job.

    404 Not Found – When the report specified in the job descriptor is not found in the server.

    When you schedule a report, you need only specify the relevant fields in the job descriptor. For example in JSON:

    The response of the PUT request is the same as the GET request shown in Viewing a Job Definition. It includes all the fields of the job descriptor, including the server-assigned ID and all the null fields.

    Viewing Job Status

    The following method returns the current run time state of a job:

    Method

    URL

    GET

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/state/

    Return Value on Success

    Typical Return Values on Failure

    200 OK – Body contains the status descriptor.

    404 Not Found – When the specified <jobID> does not exist.

    Editing a Job Definition

    The POST method replaces the entire definition of a job with a new descriptor. To modify an existing job definition, use the GET method to read its job descriptor, modify the descriptor as required, then use the POST method of the jobs service.

    Method

    URL

    POST

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/

    Content-Type

    Content

    application/job+xml

    application/job+json

    A well-formed XML or JSON job descriptor. The request can include either a complete descriptor such as the result of a GET request described in Viewing a Job Definition, or it can be a minimally sufficient descriptor as shown in Scheduling a Report.

    Options

    accept: application/job+xml

    accept: application/job+json

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The response include the complete job descriptor, for an example, see Viewing a Job Definition.

    404 Not Found – When the specified <jobID> does not exist.

    Updating Jobs in Bulk

    The POST method also supports other parameters to perform bulk updates on scheduled jobs.

    Method

    URL

    POST

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?<arguments>

    Argument

    Type/Value

    Description

    id?

    jobID string

    Can be used multiple times to create a list of job IDs to update.

    replace
    Trigger
    IgnoreType

    true / false

    Specify true when you send a new trigger type. By default, this is false, and the trigger can be updated but not changed to a different type. See below.

    Content-Type

    Content

    application/json

    application/xml

    A well-formed jobModel descriptor, which is a fragment of a job descriptor containing only the fields to be updated. See example below.

    Options

    accept: application/json

    accept: application/xml

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The array or list of jobs that were restarted.

    404 Not Found – When the specified <jobID> does not exist.

    In this usage, the POST method allows you to send a partial job description, called a jobModel, that contains any subset of the job descriptor's fields. This update applies to one or more jobs whose ID is specified by the id argument. For example, the following simple request will update the job description in several jobs:

    However, the jobModel provides two mechanisms to create complex updates:

    You can describe nested structures by using the nestedNameModel equivalent element. Like the jobModel, nested model elements contain only the subset that you want to modify. Thus you could change one value within a parameter, the end date within a schedule, or an email address within a notification.
    You can remove the definition of an element by using the isElementNameModified element and giving it the value true. This indicates that the element's new value is null, and thus that the element should be removed altogether from the job descriptor.

    In the following example, the description will be removed from the target jobs, and their triggers will be modified. Note that XML descriptors do not use the trigger element and thus do not have a triggerModel element:

    The response has an array or list of jobId elements that were updated:

    JSON: {"jobId":[8321,8322]}XML:  <jobIdList>          <jobId>8321</jobId>          <jobId>8322</jobId>      </jobIdList>[/code]                    

    Pausing Jobs

    The following method pauses currently scheduled job execution. Pausing keeps the job schedule and all other details but prevents the job from running. It does not delete the job.

    Method

    URL

    POST

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/pause/

    Content-Type

    Content

    application/xml

    application/json

    An array or list of job IDs to pause. See example below. If the body of the request is empty, or the list is empty, all jobs in the scheduler will be paused.

    Options

    accept: application/json

    accept: application/xml

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The array or list of jobs that were paused.

     

    The request and the response have the same format, an array or list of jobId elements:

    JSON: {"jobId":[1236,1237,1238,1239]}XML:  <jobIdList>          <jobId>1236</jobId>          <jobId>1237</jobId>          <jobId>1238</jobId>          <jobId>1239</jobId>      </jobIdList>[/code]                    

    Resuming Jobs

    Use the following method to resume any or all paused jobs in the scheduler. Resuming a job means that any defined trigger in the schedule that occurs after the time it is resumed will cause the report to run again. Missed schedule triggers that occur before the job is resumed are never run.

    Method

    URL

    POST

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/resume/

    Content-Type

    Content

    application/xml

    application/json

    An array or list of job IDs to resume. See example below. If the body of the request is empty, or the list is empty, all paused jobs in the scheduler will resume.

    Options

    accept: application/json

    accept: application/xml

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The array or list of jobs that were resumed.

     

    The request and the response have the same format, an array or list of jobId elements:

    JSON: {"jobId":[1236,1237]}XML:  <jobIdList>          <jobId>1236</jobId>          <jobId>1237</jobId>      </jobIdList>[/code]                    

    Restarting Failed Jobs

    Use the following method to rerun failed jobs in the scheduler. For each job to be restarted, the scheduler creates an immediate single-run copy of job, to replace the one that failed. Therefore, all jobs listed in the request body will run once immediately after issuing this command. The single-run copies have a misfire policy set so that they do not trigger any further failures (MISFIRE_ INSTRUCTION_IGNORE_MISFIRE_POLICY). If the single-run copies fail themselves, no further attempts are made automatically.

    Method

    URL

    POST

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/restart/

    Content-Type

    Content

    application/xml

    application/json

    An array or list of job IDs to restart. See example below.

    Options

    accept: application/json

    accept: application/xml

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The array or list of jobs that were restarted.

     

    The request and the response have the same array or list of jobId elements:

    JSON: {"jobId":[8321,8322]}XML:  <jobIdList>          <jobId>8321</jobId>          <jobId>8322</jobId>      </jobIdList>[/code]                    

    Deleting Jobs

    Use the DELETE method to remove jobs from the scheduler. There are two forms to specify a single job or multiple jobs to delete.

    Method

    URL

    DELETE

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The body contains the ID of the deleted job.

    404 Not Found – When the specified job is not found in the server.

     

    Method

    URL

    DELETE

    http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?<arguments>

    Argument

    Type/Value

    Description

    id

    Multiple String

    Enter as many job IDs as you want to delete, for example:

    ?id=5594&id=5645&id=5761

    Options

    accept: application/xml

    accept: application/json

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The content is a list of deleted jobs, as shown in the example below.

     

    The list of deleted jobs in the response has an array or list of jobId elements:

    JSON: {"jobId":[5594,5645,5761]}XML:  <jobIdList>          <jobId>5594</jobId>          <jobId>5645</jobId>          <jobId>5761</jobId>      </jobIdList>[/code]                    

    Specifying FTP Output

    The REST service allows a job to specify output to remote files through FTP (File Transfer Protocol). In addition to the repository location, you can specify an FTP server and path where JasperReports Server will write the output files when the job runs. You also need to provide a username and password to access the FTP server.

    To specify these parameters, add the outputFTPInfo element to the XML job descriptor, as shown in the following example:

    FTP output is always specified in addition to repository output, and the output will be written to both the repository and the FTP location. You cannot specify FTP output alone. The file names to be written are the same ones that are generated by the job output, as specified by the baseOutputFilename, sequential pattern if any, and format extensions such as .pdf. Similarly, the file overwrite and sequential filename behavior specified for repository output also apply to FTP output.

    As of JasperReports Server 6.3, FTP output also supports SSH private keys stored in the repository for authentication. All of the fields for the outputFTPInfo element are described in the following table:

    Field Description JSON Example

    type

    Type of FTP connection requested: ftp (default), ftps, or sftp.

    "type": "{ftp|ftps|sftp}"

    serverName

    The host name of the FTP server.

    "serverName": "ftp.example.com"

    port

    Integer value that specifies the port number of the ftp server. The default value depends on the connection type: ftp = 21, sftp = 22, and ftps = 990.

    "port": 21

    userName

    The login user name for the FTP server.

    "userName": "anonymous"

    password

    The login password for the given userName on the FTP server.

    "password": "securePassword"

    folderPath

    The path of the folder where the job output resources should be created.

    "folderPath": "/path/to/folder"

    implicit

    Specifies the security mode for FTPS, Implicit if true (default) or Explicit if false. If implicit is true, the default port is set to 990.

    "implicit": {true|false}

    protocol

    Specifies the secure socket protocol to be used, for example SSL or TLS.

    "protocol": "TLS"

    prot

    Specifies the PROT command for FTP. Supported values:

    C - Clear
    S - Safe (SSL protocol only)
    E - Confidential (SSL protocol only)
    P - Private

    "prot": "C"

    pbsz

    Specifies the protection buffer size: 0 to (2^32)-1 decimal integer. The default is 0.

    "pbsz": 0

    sshKey

    Repository URI of the SSH private key resource (used for SFTP authentication).

    "sshKey": "/sshKeys/myOpenSSHKey"

    sshPassphrase

    The passphrase for the SSH private key (used for SFTP authentication).

    "sshPassphrase": "mySecurePhrase"

    Administrators can store SSH key files in the repository by right-clicking a folder and selecting Add Resource > File > Secure File from the context menu. For more information, see the JasperReports Server Administrator Guide.

    Specifying File System Output

    When configured, you can also specify a path on the local file system to write job output. The user running the server process must have write permission in that location.

    In order for file system output to work, the server must be properly configured. In the file .../WEB-INF/applicationContext.xml, you must set the enableSaveToHostFS property to true. As described in the configuration chapter of the JasperReports Server Administrator Guide, this setting also enables file system output from the scheduler user interface for all users, which could be a security risk.

    To create a job with file system output, add the outputLocalFolder element to the XML job descriptor, as shown in the following example:

    As with FTP output, file system output is always specified in addition to repository output, and the output will be written to both the repository and the local folder. The file names to be written are the same ones that are generated by the job output, as specified by the baseOutputFilename, sequential pattern if any, and format extensions such as .pdf. Similarly, the file overwrite and sequential filename behavior specified for repository output also apply to file system output.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...