Asynchronous Requests

SCI requests that are asynchronous return without waiting for the request to finish, and return a job ID that can be used to retrieve the status and results later.

If you POST an SCI request asynchronously and want to see the results, the general flow is:

POST the SCI request.

if rc=202 // The job is accepted
      get the location from the response header or the job ID from the response content
      rc = HEAD location
      while rc!=200
            sleep for a number of seconds
            rc = HEAD location
      GET location
      process your results
      DELETE location

Performing an Asynchronous Request

A synchronous request is performed by specifying synchronous=“false” in the element specifying the operation in the request, e.g.: <send_message synchronous="false">

the response then has the form:

<sci_reply version="1.0">
   <send_message>
      <jobId>{job_id}</jobId>
   </send_message>
</sci_reply>

where job_id identifies the request you submitted.

Retrieve Status

You can retrieve the status for a particular request, or retrieve information about submitted requests overall.

Status for a Particular Job

Do an HTTP GET on /ws/sci/{job_id}

To determine if a job is complete, do an HTTP HEAD specifying the job ID; /ws/sci/601358. A return code of 200 means the job is complete.

Overall Status of Outstanding Jobs

Do an HTTP GET on /ws/sci, and you will get a response that looks like:

<result>
   <resultTotalRows>1</resultTotalRows>
   <requestedStartRow>0</requestedStartRow>
   <resultSize>1</resultSize>
   <requestedSize>1000</requestedSize>
   <remainingSize>0</remainingSize>
   <Job>
      <jobId>601358</jobId>
      <cstId>0</cstId>
      <usrId>0</usrId>
      <jobType>0</jobType>
      <jobSyncMode>0</jobSyncMode>
      <jobReplyMode>0</jobReplyMode>
      <jobTargets>00000000-00000000-0004F3FF-00000000</jobTargets>
      <jobRequestPayload>&lt;rci_request&gt;&lt;query_setting/&gt;&lt;/rci_request&gt;</jobRequestPayload>
      <jobDescription>query_setting</jobDescription>
      <jobStatus>2</jobStatus>
      <jobTargetCount>1</jobTargetCount>
      <jobProgressSuccess>1</jobProgressSuccess>
      <jobProgressFailures>0</jobProgressFailures>
      <jobSubmitTime>2010-03-02T15:36:22Z</jobSubmitTime>
      <jobCompletionTime>2010-03-02T15:36:22Z</jobCompletionTime>
   </Job>
</result>

where jobId is the ID for the request. jobType is the type of the job (0: send_message, 1: update_firmware, 2: disconnect). jobSyncMode indicates if the job is synchronous (0: synchronous, 1: asynchronous). jobReplyMode indicates the reply mode (0: all, 1: none, 2: only), where only means only return errors. jobStatus is the current status of the job (0: new, 1: in_progress, 2: complete, 3: canceled). jobTargetCount is the number of devices the job is targeted for. jobProgressSuccess is the number of devices that have completed the operation successfully. jobProgressFailures is the number of devices that have completed the operation with an error.

Retrieve Progress

You can retrieve the progress for a particular SCI job by specifying the progress=true parameter. For example:

HTTP GET https://remotemanager.digi.com/ws/sci/{job_id}?progress=true

This will return the current progress (percent completion) for an SCI job, as well as its progress history. For example, let’s assume we have an SCI job that is performing a firmware update on two different devices. Performing the query shown above will give a response that looks something like:

<sci_reply version="1.0">
   <status>in_progress</status>
   <update_firmware>
      <device id="00000000-00000000-000000FF- FF000001">
         <progress time="Mon Nov 28 21:30:25 UTC 2011" status="0">Getting Target Info</progress>
         <progress time="Mon Nov 28 21:30:27 UTC 2011" status="0">Sending Download Request</progress>
         <progress time="Mon Nov 28 21:31:15 UTC 2011" status="5">Sending Data: 156672 out of 3130662 bytes sent</progress>
         <progress time="Mon Nov 28 21:32:07 UTC 2011" status="10">Sending Data: 313344 out of 3130662 bytes sent</progress>
      </device>
      <device id="00000000-00000000-000000FF- FF000002">
         <progress time="Mon Nov 28 21:30:26 UTC 2011" status="0">Getting Target Info</progress>
         <progress time="Mon Nov 28 21:30:27 UTC 2011" status="0">Sending Download Request</progress>
         <progress time="Mon Nov 28 21:31:05 UTC 2011" status="5">Sending Data: 156672 out of 3130662 bytes sent</progress>
         <progress time="Mon Nov 28 21:31:48 UTC 2011" status="10">Sending Data: 313344 out of 3130662 bytes sent</progress>
         <progress time="Mon Nov 28 21:32:30 UTC 2011" status="15">Sending Data: 470016 out of 3130662 bytes sent</progress>
      </device>
   </update_firmware>
</sci_reply>

We can also query for job progress on other types of SCI jobs, including file uploads through the File System service. Progress updates for file uploads through RCI is not supported.

Cancel a Request or Delete the Results

Do an HTTP DELETE on /ws/sci/{job id}

This will attempt to cancel the request. Some parts of the request may have already completed, and parts of the request that are in progress may continue to completion, but it should prevent any operations that have not yet begun from starting.