AgileApps Support Wiki Pre Release

REST API:Status Resources

From AgileApps Support Wiki
Revision as of 19:59, 12 June 2014 by imported>Aeric
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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
<syntaxhighlight lang="xml" enclose="div">

<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> 
           <status>In Processing Queue</status>
           <statusCode>1</statusCode>
           <date_created>2010-12-19T05:50:18.000Z</date_created>
           <created_id type="USER"
              uri="https://{yourDomain}/networking/rest/user/qwe123rty456" 
              displayValue="Rita Goodbook">qwe123rty456</created_id>
       </import>
   </status>

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

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
  • 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:
<syntaxhighlight lang="xml" enclose="div">

<platform> 

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

  <totalRecordCount>N</totalRecordCount>

</platform> </syntaxhighlight>

  • 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
<syntaxhighlight lang="xml" enclose="div">

<platform> 

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

</platform> </syntaxhighlight>

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
<syntaxhighlight lang="xml" enclose="div">

<platform> <status> 

   <packageDeploy>

<date_created>2011-01-08T14:24:03Z</date_created> <created_id type="USER" uri="https://{yourDomain}/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>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

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
  • 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:
<syntaxhighlight lang="xml" enclose="div">

<platform> 

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

  <totalRecordCount>N</totalRecordCount>

</platform> </syntaxhighlight>

  • 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
<syntaxhighlight lang="xml" enclose="div">

<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>
       0
       <description>Success</description>
   </message>
   <recordCount>2</recordCount>

</platform> </syntaxhighlight>

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

Lock-tiny.gif

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):

<syntaxhighlight lang="xml" enclose="div">

<platform> 

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

</platform> </syntaxhighlight>

Get Job Details

Method
GET
URI
https://{yourDomain}/networking/rest/scheduledJob/{jobId}
Response
<syntaxhighlight lang="xml" enclose="div">

<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>
   0
   <description>Success</description>
 </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Delete a Job

Method
DELETE
URI
https://{yourDomain}/networking/rest/scheduledJob/{jobId}
Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

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
  • 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:
<syntaxhighlight lang="xml" enclose="div">

<platform> 

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

  <totalRecordCount>N</totalRecordCount>

</platform> </syntaxhighlight>

  • 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
<syntaxhighlight lang="xml" enclose="div">

<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>
   0
   <description>Success</description>
 </message>

</platform> </syntaxhighlight>

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.
<syntaxhighlight lang="xml" enclose="div">

<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>
   0
   <description>Success</description>
   </message>
   <recordCount>6</recordCount>
 </platform>

</syntaxhighlight>

Fields

Note: Unless otherwise indicated, the attribute for a field is "Editable on Add or Update".
Name Type Attribute Required During Add 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}
Retrieved from "https://agileappscloud.info/aadev-src/index.php?title=REST_API:Status_Resources&oldid=12992"