REST API:Status Resources

Use these resources to get status information on jobs that were submitted to the scheduler from the GUI, from Java APIs, or from the REST API.

Learn more: REST API Conventions and Considerations.

Import Status

Get Import Status

Report on the status of import jobs undertaken through the GUI, or using the REST bulk upload Resource.

Method: GET

URI: https://{yourDomain}/networking/rest/status/import/{job_id}

Response

<platform>
    <status>
        <import>
            <id>197rfy238qaz</id>
            <fileName>emp1.csv</fileName>
            <mapping>
|CONTACT_COUNTRY,5|NAME,0|COUNTRY,5|BILLING_ACCOUNT,3|NUMBER,1
            </mapping>
            <totalRecords>5</totalRecords>
            <addedRecords>0</addedRecords>
            <mergedRecords>0</mergedRecords>

            <ignoredRecords>0</ignoredRecords> 
            <!--Rejections are recorded in <ignoredReason>, if any--> 
            <status>In Processing Queue</status>
            <statusCode>1</statusCode>
            <date_created>2010-12-19T05:50:18.000Z</date_created>
            <created_id type="USER"
               uri="https://{{domain}}/networking/rest/user/qwe123rty456" 
               displayValue="Rita Goodbook">qwe123rty456</created_id>
        </import>
    </status>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Dynamic Search for Import Status Records

Method: GET

URI: https://{yourDomain}/networking/rest/status/import?{query_parameters}

Sample Search: ?fieldList=fileName,status&filter=objectName contains 'contact'; (Field names are in the Fields section.)

Query Parameters

fieldList - A comma-separated list of field names to retrieve

The asterisk (*) wildcard specifies all fields
{fieldname} specifies an individual field (e.g. name)

(Use the REST API:field Resource to get a complete list of fields.)

For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
alias.* specifies all fields in the aliased object.

filter - Filtering criteria to filter the records

For more examples, see Filter Expressions in REST APIs and the REST API Examples.)

pageSize - Number of records to retrieve from the result set in order to make a "page".
page - Number of the logical page in a database result set. The first page is page "zero" (0).

Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.

getTotalRecordCount returns the number of total records.
Causes the following structure to be returned, where N is the total number of records:

<platform> 
   <status>
   <packageDeploy>
   ...
   </packageDeploy>
   </status>
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>

sortBy - Field name for primary sort
Ex: &sortBy=name
sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
Ex: &sortOrder=desc
sortBy2 - Field name for secondary sort
sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)

For more information, see: Specifying Query Parameters in REST APIs

Response

<platform>
    ....
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Fields

Name	Type	Description
id	String	ID of the scheduled import job
filename	String	Data file used for upload
mapping	String	Name of the Mapping profile used for import
totalRecords	String	Number of records in the file
addedRecords	String	Number of added records
mergedRecords	String	Number of merged records
ignoredRecords	String	Number of rejected Records
ignoredReason	String	A list of up to 50 rejection messages, separated by asterisks (*). (This field only appears if one or more records are rejected.)
statusCode	String	Status code. (See table below)
status	String	Status message (See table below)
objectName	String	Object into which data is imported
processStartDate	Date	Date and time the import started, in UTC Format
processEndDate	Date	Date and time the import completed, in UTC Format
date_created	Date	Date and time the import job was submitted, in UTC Format
created_id	Lookup	ID of the User who created the job

Scheduled jobs may be in one of the following states. (Constants are defined in com.platform.api.CONSTANTS.STATUS)

statusCode (int)	status (String)	Description
IN_PROCESS_QUEUE	"In process queue"	Job has been accepted by the scheduler.
STARTED	"Started"	Job is currently being processed.
COMPLETED	"Completed"	Job finished.
WAITING_TO_BE_STOPPED	"Waiting to be stopped"	Job started, but user has issued a STOP request. Processing is continuing until an appropriate stopping-point is reached. (Note: The STOP operation is not available for all jobs.)
STOPPED	"Stopped"	Job was stopped by user.

Package Deployment Status

Get Package Deployment Status

Method: GET

URI: https://{yourDomain}/networking/rest/status/packageDeploy/{jobId}

Response

<platform>
<status>
    <packageDeploy>
	<date_created>2011-01-08T14:24:03Z</date_created>
	<created_id type="USER" 
	  uri="https://{{domain}}/networking/rest/user/qwe123rty456" 
	  displayValue="Smith Bob">qwe123rty456</created_id>
        <id>zig789fez098</id>
	<packageName>Order Processing</packageName>
	<totalDeployments>2</totalDeployments>
	<successfulDeployments>2</successfulDeployments>
	<failedDeployments>0</failedDeployments>
	<summary>
         1096387182;;Tenant1;;1;;N/A||1254445340;;Tenant2;;1;;N/A||
	</summary>
	<statusCode>4</statusCode>
	<status>Deployment Completed</status>
	<processStartDate>2011-01-09T02:00:00Z</processStartDate>
	<processEndDate>2011-01-09T02:00:03Z</processEndDate>
    </packageDeploy>
</status>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Dynamic Search for Package Deployment Status Records

Method: GET

URI: https://{yourDomain}/networking/rest/status/packageDeploy?{query_parameters}

Query Parameters

fieldList - A comma-separated list of field names to retrieve

The asterisk (*) wildcard specifies all fields
{fieldname} specifies an individual field (e.g. name)

(Use the REST API:field Resource to get a complete list of fields.)

For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
alias.* specifies all fields in the aliased object.

filter - Filtering criteria to filter the records

For more examples, see Filter Expressions in REST APIs and the REST API Examples.)

pageSize - Number of records to retrieve from the result set in order to make a "page".
page - Number of the logical page in a database result set. The first page is page "zero" (0).

Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.

getTotalRecordCount returns the number of total records.
Causes the following structure to be returned, where N is the total number of records:

<platform> 
   <status>
   <packageDeploy>
   ...
   </packageDeploy>
   </status>
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>

sortBy - Field name for primary sort
Ex: &sortBy=name
sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
Ex: &sortOrder=desc
sortBy2 - Field name for secondary sort
sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)

For more information, see: Specifying Query Parameters in REST APIs

Sample Search: ?fieldList=packageName,id,status,processEndDate; (Field names are in the Fields section.)

Response

<platform>
    <status>
        <packageDeploy>
            <id>far987bar6544</id>
            <packageName>Inventory Management</packageName>
            <status>Deployment Completed</status>
            <processEndDate>2011-01-09T12:01:03Z</processEndDate>
        </packageDeploy>
    </status>
	
    <status>
        <packageDeploy>
            <id>zig789fez098</id>
            <packageName>Order Processing</packageName>
            <status>Deployment Completed</status>
            <processEndDate>2011-01-09T12:01:58Z</processEndDate>
        </packageDeploy>
    </status>
	 
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
    <recordCount>2</recordCount>
</platform>

See also: REST API:Error Codes

Fields

Name	Type	Description
id	String	ID of the scheduled package-deployment job
packageName	String	Name of the package that was deployed.
totalDeployments	String	Number of deployments attempted
successfulDeployments	String	Number of deployments that succeeded
failedDeployments	String	Number that failed
summary	String	A string showing the results of all deployments, following the pattern: `{tenant1 ID};; {tenant1 name};; 1;; N/A \|\| {tenant2 ID};; {tenant2 name};; 0;; {failure message}` where: Records are separated by `\|\|` Fields are separated by `;;` 1 is the success code, followed by "N/A" (not applicable) 0 is the failure code, followed by a failure message
statusCode	String	Status code. (See table below)
status	String	Status message. (See table below)
objectName	String	Object into which data is imported
processStartDate	Date	Date and time the import started, in UTC Format
processEndDate	String	Date and time the import completed, in UTC Format
date_created	Date	Date and time the import job was submitted, in UTC Format
created_id	Lookup	ID of the User who created the job

Scheduled jobs may be in one of the following states. (Constants are defined in com.platform.api.CONSTANTS.STATUS)

statusCode (int)	status (String)	Description
IN_PROCESS_QUEUE	"In process queue"	Job has been accepted by the scheduler.
STARTED	"Started"	Job is currently being processed.
COMPLETED	"Completed"	Job finished.
WAITING_TO_BE_STOPPED	"Waiting to be stopped"	Job started, but user has issued a STOP request. Processing is continuing until an appropriate stopping-point is reached. (Note: The STOP operation is not available for all jobs.)
STOPPED	"Stopped"	Job was stopped by user.

Scheduled Jobs

Manage scheduled jobs using the REST API.

Learn more: REST API Conventions and Considerations.

Permissions

Users that have the Use Development Features permission can use this resource.

Schedule a Job

If a class has been defined like the one described in Schedule a Job, the REST exec Resource can be used to schedule the job: Schedule the job by using the REST class/operation/exec resource to invoke the method in that class that does the scheduling (run):

URL: https://{yourDomain}/networking/rest/class/operation/exec
Request type: application/xml
Request body:

<platform>
  <execClass>
    <clazz>com.platform.demo.cron.CronJobDemo</clazz>
    <method>run</method>
  </execClass>
</platform>

Get Job Details

Method: GET

URI: https://{yourDomain}/networking/rest/scheduledJob/{jobId}

Response

<platform>
  <scheduledJob>
    <jobId>1eb2f5b694bf4a94974bf7b5a2340ab2</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T15:29:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>
  
  <message>
    <code>0</code>
    <description>Success</description>
  </message>
</platform>

See also: REST API:Error Codes

Delete a Job

Method: DELETE

URI: https://{yourDomain}/networking/rest/scheduledJob/{jobId}

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Dynamic Search of Job History

Method: GET

URI

https://{yourDomain}/networking/rest/scheduledJob?{query_parameters}

Sample Search: ?fieldList=name,id&filter=name contains 'smith' & sortby='id'; (Field names are in the Fields section.)

Query Parameters

fieldList - A comma-separated list of field names to retrieve

The asterisk (*) wildcard specifies all fields
{fieldname} specifies an individual field (e.g. name)

(Use the REST API:field Resource to get a complete list of fields.)

For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
alias.* specifies all fields in the aliased object.

filter - Filtering criteria to filter the records

For more examples, see Filter Expressions in REST APIs and the REST API Examples.)

pageSize - Number of records to retrieve from the result set in order to make a "page".
page - Number of the logical page in a database result set. The first page is page "zero" (0).

Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.

getTotalRecordCount returns the number of total records.
Causes the following structure to be returned, where N is the total number of records:

<platform> 
   <status>
   <packageDeploy>
   ...
   </packageDeploy>
   </status>
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>

sortBy - Field name for primary sort
Ex: &sortBy=name
sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
Ex: &sortOrder=desc
sortBy2 - Field name for secondary sort
sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)

For more information, see: Specifying Query Parameters in REST APIs

Response

<platform>
  <scheduledJob>
    <jobId>1eb2f5b694bf4a94974bf7b5a2340ab2</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T15:29:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>
   ...
  <message>
    <code>0</code>
    <description>Success</description>
  </message>
</platform>

See also: REST API:Error Codes

Notes:

The response is a job history. If a job is scheduled and then deleted, there will be two entries with the same ID. The last entry shows the current status (deleted).
If rescheduled, the job will get a new ID, which makes it a separate job.
Entries are also added every time the job is executed, showing the time when execution occurred.

Example: Get a Complete Job History

This call returns a complete history of all jobs (scheduled, deleted, and executed) since the platform was installed. For example:

https://{yourDomain}/networking/rest/scheduledJob?fileList=*

Response: In this example, a job was scheduled, deleted, and re-scheduled. It was then executed twice.

<platform>
  <scheduledJob>
    <jobId>1eb2f5b694bf4a94974bf7b5a2340ab2</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T15:29:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>1eb2f5b694bf4a94974bf7b5a2340ab2</jobId>
    <jobName>Daily Task</jobName>
    <lastExecutionTime>2010-11-15T17:32:00-08:00</lastExecutionTime>
    <status>Job Deleted</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>7c4d4e54ee2143b49abf38ec5863af06</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T17:36:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>d4feb5d38a96492fab5f8d9cb4d3c9dc</jobId>
    <jobName>Daily Task</jobName>
    <scheduledDate>2010-11-15T17:57:00-08:00</scheduledDate>
    <nextExecutionTime>2010-11-16T03:00:00-08:00</nextExecutionTime>
    <status>Job Scheduled</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>7c4d4e54ee2143b49abf38ec5863af06</jobId>
    <jobName>Daily Task</jobName>
    <lastExecutionTime>2010-11-16T03:00:00-08:00</lastExecutionTime>
    <nextExecutionTime>2010-11-17T03:00:00-08:00</nextExecutionTime>
    <status>Executed Successfully</status>
  </scheduledJob>

  <scheduledJob>
    <jobId>d4feb5d38a96492fab5f8d9cb4d3c9dc</jobId>
    <jobName>Daily Task</jobName>
    <lastExecutionTime>2010-11-16T03:00:00-08:00</lastExecutionTime>
    <nextExecutionTime>2010-11-17T03:00:00-08:00</nextExecutionTime>
    <status>Executed Successfully</status>
  </scheduledJob>

  <message>
    <code>0</code>
    <description>Success</description>
    </message>
    <recordCount>6</recordCount>
  </platform>

Fields

Note: Unless otherwise indicated, the attribute for a field is "Editable on Add or Update".

Name	Type	Attribute	Description	Additional Information
jobId	String	Read Only	Job identifier	Used for individual-job requests
jobName	String	Read Only	Name given to the job when created
cronExpression	String	Read Only	Expression that tells when the job is to be run.	Cron Expression
runAsUser	String	Read Only	User ID	Who to be when the job runs
scheduledDate	String	Read Only	Date and time the job was created.
nextExecutionTime	String	Read Only	The next time the job will run
lastExecutionTime	String	Read Only	The last time the job was run
status	String	Read Only	One of: Job Scheduled Job Deleted Executed Successfully Error {message}

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools

REST API:Status Resources

Contents

Import Status

Get Import Status

Dynamic Search for Import Status Records

Fields

Package Deployment Status

Get Package Deployment Status

Dynamic Search for Package Deployment Status Records

Fields

Scheduled Jobs

Permissions

Schedule a Job

Get Job Details

Delete a Job

Dynamic Search of Job History

Example: Get a Complete Job History

Fields