The jobs Service

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:

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.

JSON: {
        "jobsummary": [
          {
            "id": 1898,
            "version": 0,
            "reportUnitURI": "/reports/AllAccounts",
            "label": "SampleJobName",
            "description": "Accounts Sample Job",
            "owner": "jasperadmin|organization_1",
            "reportLabel": "Accounts Report",
            "state": {
              "previousFireTime": null,
              "nextFireTime": "2013-10-12T00:00:00+03:00",
              "value": "NORMAL"
            }
          },
          ...
        ]
      }
 
XML:  <jobs>
          <jobsummary>
              <id>1898</id>
              <label>SampleJobName</label>
              <description>Accounts Sample Job</description>
              <reportUnitURI>/reports/AllAccounts</reportUnitURI>
              <reportLabel>Accounts Report</reportLabel>
              <state>
                  <nextFireTime>2013-10-12T00:00:00+03:00</nextFireTime>
                  <value>NORMAL</value>
              </state>
              <owner>jasperadmin|organization_1</owner>
              <version>0</version>
          </jobsummary>
          ...
      </jobs>

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, in the format username|organization.

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:

{
    "id": 1906,
    "version": 0,
    "username": "jasperadmin|organization_1",
    "label": "Sample Job Name",
    "description": "Sample desctiption",
    "creationDate": "2013-10-11T14:52:04.955+03:00",
    "outputFormats": {
        "outputFormat": ["XLS",
        "PDF"]
    }
    "trigger": {
        "simpleTrigger": {
            "id": 0,
            "version": 0,
            "timezone": "America/Los_Angeles",
            "calendarName": null,
            "startType": 2,
            "startDate": "2016-10-26 10:00",
            "endDate": null,
            "misfireInstruction": 0,
            "occurrenceCount": 1,
            "recurrenceInterval": null
        }
    },
    "source": {
        "reportUnitURI": "/adhoc/topics/Cascading_multi_select_topic",
        "parameters": {
            "parameterValues": {
                "Country_multi_select": ["Mexico"],
                "Cascading_name_single_select": ["Chin-Lovell Engineering Associates"],
                "Cascading_state_multi_select": ["DF",
                "Jalisco",
                "Mexico"]
            }
        }
    },
    "alert": {
        "id": 0,
        "version": -1,
        "recipient": "OWNER_AND_ADMIN",
        "toAddresses": {
            "address": []
        },
        "jobState": "FAIL_ONLY",
        "messageText": null,
        "messageTextWhenJobFails": null,
        "subject": null,
        "includingStackTrace": true,
        "includingReportJobInfo": true
    },
    "baseOutputFilename": "Cascading_multi_select_report",
    "outputLocale": null,
    "mailNotification": null,
    "outputTimeZone": null,
    "repositoryDestination": {
        "id": 0,
        "version": -1,
        "folderURI": "/temp",
        "sequentialFilenames": false,
        "overwriteFiles": false,
        "outputDescription": null,
        "timestampPattern": null,
        "saveToRepository": true,
        "defaultReportOutputFolderURI": null,
        "usingDefaultReportOutputFolderURI": false,
        "outputLocalFolder": null,
        "outputFTPInfo": {
            "userName": "anonymous",
            "password": null,
            "folderPath": null,
            "serverName": null,
            "type": "ftps",
            "protocol": null,
            "port": 990,
            "implicit": true,
            "pbsz": 0,
            "prot": null
        }
    },
}

XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<clientJob>
    <creationDate>2015-11-05T13:38:09.759+02:00</creationDate>
    <id>5484</id>
    <label>test</label>
    <username>superuser</username>
    <version>0</version>
    <outputFormats>
        <outputFormat>PDF</outputFormat>
    </outputFormats>
    <simpleTrigger>
        <id>5482</id>
        <misfireInstruction>0</misfireInstruction>
        <startDate>2015-11-06T00:00:00+02:00</startDate>
        <startType>2</startType>
        <timezone>Europe/Helsinki</timezone>
        <version>0</version>
        <occurrenceCount>1</occurrenceCount>
        <startDate>2015-11-06 00:00</startDate>
    </simpleTrigger>
    <source>
        <parameters>
            <parameterValues>
                <entry>
                    <key>Country_multi_select</key>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="collection">
                        <item xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Mexico</item>
                    </value>
                </entry>
                <entry>
                    <key>Cascading_name_single_select</key>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="collection">
                        <item xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Chin-Lovell Engineering Associates</item>
                    </value>
                </entry>
                <entry>
                    <key>Cascading_state_multi_select</key>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="collection">
                        <item xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">DF</item>
                        <item xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Jalisco</item>
                        <item xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Mexico</item>
                    </value>
                </entry>
            </parameterValues>
        </parameters>
        <reportUnitURI>/organizations/organization_1/adhoc/topics/Cascading_multi_select_topic</reportUnitURI>
    </source>
    <outputTimeZone>Europe/Helsinki</outputTimeZone>
    <baseOutputFilename>Cascading_multi_select_topic</baseOutputFilename>
    <repositoryDestination>
        <folderURI>/organizations/organization_1/adhoc/topics</folderURI>
        <id>5483</id>
        <outputFTPInfo>
            <implicit>true</implicit>
            <password/>
            <pbsz>0</pbsz>
            <port>21</port>
            <type>ftp</type>
            <userName>anonymous</userName>
        </outputFTPInfo>
        <overwriteFiles>true</overwriteFiles>
        <saveToRepository>true</saveToRepository>
        <sequentialFilenames>false</sequentialFilenames>
        <usingDefaultReportOutputFolderURI>false</usingDefaultReportOutputFolderURI>
        <version>-1</version>
    </repositoryDestination>
</clientJob>

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:

{
    "label": "Sample Job Name",
    "description": "Sample desctiption",
    "trigger": {
        "simpleTrigger": {
            "timezone": "America/Los_Angeles",
            "startType": 2,
            "startDate": "2013-10-26 10:00",
            "occurrenceCount": 1
        }
    },
    "source": {
        "reportUnitURI": "/adhoc/topics/Cascading_multi_select_topic",
        "parameters": {
            "parameterValues": {
                "Country_multi_select": ["Mexico"],
                "Cascading_name_single_select": ["Chin-Lovell Engineering Associates"],
                "Cascading_state_multi_select": ["DF",
                "Jalisco",
                "Mexico"]
            }
        }
    },
    "baseOutputFilename": "Cascading_multi_select_report",
    "outputTimeZone": "America/Los_Angeles",
    "repositoryDestination": {
        "folderURI": "/temp"
    },
    "outputFormats": {
        "outputFormat": ["PDF", "XLS"]
    }
}

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:

POST http://localhost:8080/jasperserver-pro/rest_v2/jobs?id=3798&id=3799&id=3800
 
<jobModel>
  <description>This description updated in bulk</description>
</jobModel>

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:

JSON: {
          "label":"Modified label",
          "isDescriptionModified":true,
          "triggerModel":{
              "simpleTriggerModel":{
                  "timezone":"Europe/Helsinki",
              }
          }
          "baseOutputFilename":"NewOutputName"
      }
XML:  <jobModel>
          <label>Modified label</label>
          <isDescriptionModified>true</isDescriptionModified>
          <simpleTriggerModel>
              <timezone>Europe/Helsinki</timezone>
          </simpleTriggerModel>
          <baseOutputFilename>NewOutputName</baseOutputFilename>
      </jobModel>

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>

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>

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>

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>

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>

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:

<job> 
    <reportUnitURI>/reports/samples/AllAccounts</reportUnitURI> 
    <label>MyJob</label>
    <description>MyJob description</description>
    <baseOutputFilename>WeeklyAccountsReport</baseOutputFilename> 
    <repositoryDestination> 
        <folderURI>/reports/samples</folderURI> 
        <overwriteFiles>true</overwriteFiles> 
        <sequentialFilenames>false</sequentialFilenames>
        <outputFTPInfo>
            <serverName>ftpserver.example.com</serverName>
            <userName>ftpUser</userName>
            <password>ftpPassword</password>
            <folderPath>/Shared/Users/ftpUser</folderPath>
        </outputFTPInfo>
    </repositoryDestination> 
    <outputFormats>
        <outputFormat>XLS</outputFormat>
        <outputFormat>PDF</outputFormat>
    </outputFormats>
  ... 
</job>

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:

<job> 
    <reportUnitURI>/reports/samples/AllAccounts</reportUnitURI> 
    <label>MyJob</label>
    <description>MyJob description</description>
    <baseOutputFilename>WeeklyAccountsReport</baseOutputFilename> 
    <repositoryDestination> 
        <folderURI>/reports/samples</folderURI> 
        <overwriteFiles>true</overwriteFiles> 
        <sequentialFilenames>false</sequentialFilenames>
        <outputLocalFolder>/temp/scheduledReports/</outputLocalFolder>
    </repositoryDestination> 
    <outputFormats>
        <outputFormat>XLS</outputFormat>
        <outputFormat>PDF</outputFormat>
    </outputFormats>
  ... 
</job>

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.

Version: 
Feedback
randomness