Questions on JobDeliveryStatus for use with Faxes

I have been taking some of the code from the VB sample and adapting it for use in my C# code.

I have quite a few questions.

First, there is code in the VB sample that inspects js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].Events and if it is set determines how many "pulls" there were, and the PullTime for each.

In my tests, "Events" has always been null. Is it relevant to faxes? In what cases would we want to look at this?

Second, I am trying to figure out the best way to get key dates from the API, notably:

The time that the job request was received by Easylink
The time that Easylink started processing to attempt the first Fax
The time that Easylink started processing for the most recent Fax attempt
The time that the Fax was completed, either successfully or in error

My request code looks like this for the request. I am requesting the status on a single job at a time in the API.

PremiereConnect.JobDeliveryStatusResult js = new PremiereConnect.JobDeliveryStatusResult();

js = PC.JobDeliveryStatus(JobStatus_Request);

I get somewhat confusing data back. For (1), I tried to use js.Status.SubmissionTime and js.Status.CompletionTime. However these two dates are always the same. I think that these are probably the time I sent the JobDeliveryStatus API request over, and are not what I want!

For (2) and (4) I am using js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].FirstAttemptTime and js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].LastAttemptTime

where currDelivery is always set to zero in my code. That seems to work well, and the dates seem to be Central TZ dates, eg. firstAttemptTime at 5/10/2011 23:14:50, lastAttemptTime at 5/10/2011 23:16:05.

Question - is there ever a case where I need to use an index other than zero for the currDelivery variable? The VB sample iterates though a number of structures and I am not sure when or why we'd ever see more than one of any of these items. Can you help me understand when there would be more than one entry for each of the following data structures during a JobDeliveryStatus?

JobDeliveryStatus
JobData
DeliveryGroup
DeliveryDetail

I am not sure what to use for (3 - the time the most recent attempt started). When we ask for the status on a Fax that is in the process of being retried, will the LastAttemptTime reflect what we need?

Once a job is finished, I see js.JobDeliveryStatus[0].JobData[0].JobState[0] == "Delivered" and js.JobDeliveryStatus[0].JobData[0].JobState.Length is > 1. When I look at js.JobDeliveryStatus[0].JobData[0].JobState[n], I see that I get 2 or 3 states for each request, e.g. state[0] is Delivered, state[1] is Posted.

Question - is there a timestamp or any additional information associated with each state? And are the states in reverse chronological order, eg state[0] is always the current state? Will there always be state [0], even for a newly submitted job? In my testing I always see a state there, such as "Delivering" or "Delivered". I am not sure why I might need to look at the subsequent status entries or what they would tell me.

In summary, below are the key variables I am referencing. RIght now currDelivery is always set to 0 in my code.

Please let me know if my field interpretation is correct; if there is anything wrong with what I am doing; and if there are possible exception conditions I might want to be aware of.

js.JobDeliveryStatus[0].JobId.MRN // the job number

js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].Destination.Value // the fax number that was used during the tranmission

js.JobDeliveryStatus[0].JobData[0].CustomerReference.Value // our supplied cref value

js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].Attempts // number of attempts made, 0 if status is Delivering

js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].FirstAttemptTime // First attempt. 1/1/0001 00:00:00 if the job has not yet started

js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].LastAttemptTime // // Last attempt or time that job finished transmitting. 1/1/0001 00:00:00 if the job has not yet started

js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].State.code // e.g. 7 for Sent, 4 for Error, 1 for Pending

js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].State.Value.ToString() // the string text matching the State.code

js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[currDelivery].State.gammacode; // the all important Gamma code

Find more posts tagged with

Comments

skamens

Wow, you do have a lot of questions! :-).

I'll try to give you some answers:

Event information (like pull events) do not apply to Fax - they generally apply only to Email (and sometimes SMS) deliveries.
As for the pieces of data you are trying to extract:

The time that the job request was received by EasyLink will be in JobDeliveryStatusResult.JobDeliveryStatus[0].JobData[0].EntryTime.
We don't really have the concept of "when we started processing to attempt the delivery". FirstAtttemptTime is "when I finished making the first attempt" (either successfully or unsuccessfully), and LastAttemptTime is "when I finished making the last attempt" (either successfully or unsuccessfully). If only one attempt was made, then they should be the same.
For a successful attempt, you could use the duration (which is returned
in RawDeliveryUnits), and subtract that from the AttemptTime to
approximate the beginning time for the attempt, if you really needed to, but I'm not sure how useful that would be.
The timestamps are returned by the system in standard XML time format. You're probably seeing them in Central time because your code is properly interpreting them for you.

As for whether you ever need to use a value other than 0 for currDelivery - it depends on how many items you have in your job. If you only ever submit jobs containing a single fax delivery, then you will only need to use 0 for this. But if you were to submit a job with multiple deliveries, you'd need to iterate through them. The number of items in the job is in the JobData.DestinationCount if you need it.
If you are always asking for delivery status on a singe job that has a single delivery, then you should always see only one of the different sections of the result (JobDeliveryStatus, JobData, DeliveryGroup, DeliveryDetail). For more complicated requests (or more complicated jobs) you might see more than one of those.
There are two types of JobStates - some are mutually exclusive, while others may be found in conjunction with others. This is mentioned in the api documentation here: https://apiforums.easylink.com/emapidocs/24/JobDeliveryStatus/JobDeliveryStatusResult.html#LN48.
There is no timestamp associated with the job states, and they are not necessarily in chronological order. For your purposes, you might want to pay attention to EntryTime (when the job came into the system), PostedTime (when all deliveries are done), and CompletionTime (when the job finishes) from the JobData section.

If you have further questions, please follow up.

LesMurphy

Thanks!

You answered almost all of my open issues.

Just a few claifications. If I look at js.JobDeliveryStatus[0].JobData[0].CompletionTime, it is always zero. Is there another place I should be looking for the Completion time? I don't know if I need that, since I have the lastAttemptTime, which gives me the completion time once the job is done.

I think the best way for me to tell if a Fax is completed is in the js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[0].State.code or .State.Value.ToString(), along with the js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[0].State.gammacode.

In the above fields I see 7/Sent or 4/Error or 1/Pending - which is exactly what I need to use in order to determine what is currently going on with the request. Can you confirm that I am already looking in the best place for the state?

I looked into the JobState array and it seems to always have Posted and Delivered, regardless of whether the Fax was successful or not. It can have Processing as a temporary state. Because it has "Delivered" even on a failure such as a Fax to an invalid phone number, I don't think the JobState helps me really understand the true status of my request.

A question on the DeliveryUnits.

The js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[0].CumulativeUnits.unit.ToString() is

is always "seconds". The documentation says it can also be pages or bytes. What controls what unit of measure is used? We always will want seconds; and I just want to make sure that I know what would cause the unit of measure to change.

Also, as FYI for other forum readers, I noticed that the js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[0].DocumentPageCount is the document page count, and I needed to add in the CoverPageCount to get the total count -- I did not see a field for the total pages in the data structure. It is simple enough to add the two fields, of course ...

skamens

Comments inline below

Just a few claifications. If I look at
js.JobDeliveryStatus[0].JobData[0].CompletionTime, it is always zero. Is
there another place I should be looking for the Completion time? I
don't know if I need that, since I have the lastAttemptTime, which gives
me the completion time once the job is done.

I just tested with one of my own jobs, and I saw a valid timestamp for CompletionTime.

Note that CompletionTime is the time the entire job is finished, including stuff that happens after the fax is delivered (usually report generation and delivery). If you need this value, you might want to try checking again a minute or so later. But as you said below, it might not matter...

I think the best way for me to tell if a Fax is completed is in
the js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[0].State.code
or .State.Value.ToString(), along with
the js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[0].State.gammacode.

In the above fields I see 7/Sent or 4/Error or 1/Pending - which is
exactly what I need to use in order to determine what is currently going
on with the request. Can you confirm that I am already looking in the
best place for the state?

This the best (and only) way to determine the status of an individual fax delivery. In your case, if you're really only doing one item per job, this will give you the information you need.

By the way - we do have options that would allow you to include multiple deliveries in a single job, with customization on a per-recipient basis. That is more efficient for the system and probably for your code as well. Is your application such that this would be a possibility?

I looked into the JobState array and it seems to always have Posted
and Delivered, regardless of whether the Fax was successful or not. It
can have Processing as a temporary state. Because it has "Delivered"
even on a failure such as a Fax to an invalid phone number, I don't
think the JobState helps me really understand the true status of my
request.

JobState talks about the phase of the job, but not the results of individual deliveries. This comment gives some details on the different job level statuses.

Again, these are generally more useful if your job has multiple items, or if you want to get a high level status of the job (is it done or not) before drilling down.

A question on the DeliveryUnits.

The js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[0].CumulativeUnits.unit.ToString() is

is always "seconds". The documentation says it can also be pages or
bytes. What controls what unit of measure is used? We always will
want seconds; and I just want to make sure that I know what would cause
the unit of measure to change.

The DeliveryUnits varies depending on the type of delivery. For a fax deliver, it's seconds. For an email delivery, it's bytes.

Note that the DeliveryUnits element actually as a "units" attribute that will tell you what it is. In the case of the fax delivery, the value will be "seconds".

Also, as FYI for other forum readers, I noticed that
the js.JobDeliveryStatus[0].JobData[0].DeliveryGroup[0].DeliveryDetail[0].DocumentPageCount
is the document page count, and I needed to add in the CoverPageCount
to get the total count -- I did not see a field for the total pages in
the data structure. It is simple enough to add the two fields, of
course ...