Document toolboxDocument toolbox

Update Job Start Time SOAP API

Owned by Matthew Wren
Jan 29, 2024
2 min read

On This Page:

Related Pages:

The sp:JobChangeStartTimeRequest API method can be used to update a job's start time.

Description

Subject to the rules for the options, changes to the job’s start time, arrival time and finish time, as well as any changes to its dispatch status, will be dispatched and, if the job is in jeopardy, the jeopardy conditions will appear on the Gantt jeopardy report in the normal way. For example: if a job is earmarked, its start time is changed by JobChangeStartTimeRequest (with SP_OptJobSetStatusBack set) so that it then falls outside the inform lead time, the job will subsequently be unearmarked. Alternatively, if a job’s completion time is made later in time and if it then overlaps another job, this will be reported as being in jeopardy.

Changes to the job’s start time, arrival time and finish time, as well as any changes to its dispatch status will subsequently become visible on the Gantt chart.

Options

This API has the following options:

Web Service

Type

Description

Req?

Val?

 

<options>

 

 

(error)

 

 

 

<setStatusBack>?</setStatusBack>

Boolean

If setStatusBack is set then the current status of the job is set back to Tentative.

(error)

 

 

 

<fixJob>?</fixJob>

Boolean

If FixJob is set the job is marked as Fixed. If, also, the job’s status is (now) Tentative, then it is positioned exactly at the times specified.

If FixJob is not set, the job’s new Start/Arrival/Finish time will determine the sequence position.

(error)

 

 

 

<allowSpanDays>?</allowSpanDays>

Boolean

If the new position of the job would span a day, the call will fail and return SP_WOULD_SPAN_DAYS (374), unless AllowSpanDays is set

(error)

 

 

</options>

 

 

 

 

Definition

The definition of this API is:

 Click here to expand...

Web Service

Type

Description

Req?

Val?

<sp:JobChangeStartTimeRequest>

 

 

 

 

 

<JobID>?</JobID>

JobID

The identifier of the job to be updated. The error SP_JOBID_INVALID (1) will be returned if the supplied JobID does not exist in the ServicePower database.

(tick)

(tick)

 

<startTime>?</startTime>

spDateTime

The job's new start date-time.

(tick)

 

 

<options>

 

 

(error)

 

 

 

 

 

See above

 

 

 

</options>

 

 

 

 

</sp:JobChangeStartTimeRequest>

 

 

 

 

The value of the three DateTime fields is local to what is specified in the tz_CJS database parameter.

This can be set such that the DateTime is local to the timezone of the region where the job is located, local to the timezone of the responsibility unit which contains the job, local to the employee that the job is allocated to, or local to a specified or default timezone.

Return Structure

The API returns the standard return structure.

Return Codes

In addition to the Standard Return Codes, the possible Return Codes from this API are:

 Click here to expand...
  • SP_OK (0)
  • SP_JOBID_INVALID (1)
  • SP_DURATION_INVALID (12)
  • SP_END_NOT_GT_START_TIME (31)
  • SP_OUTSIDE_HORIZON (53)
  • SP_OPTIONS_INVALID (80)
  • SP_UNRESOURCED_JOB (148)
  • SP_OUTSIDE_FRU_POSTING (264)
  • SP_OK_WITH_OVERLAPS (373)
  • SP_WOULD_SPAN_DAYS (374)
  • SP_DST_TIME_INVALID (379)
  • SP_START_MOVED_TOO_FAR (386)
  • SP_ARRIVES_ON_ANOTHER_DAY (387)
  • SP_JOB_TOO_LONG (388)
  • SP_DATETIME_INVALID (538)

 

SP_DURATION_INVALID (12) is returned if the job’s new Finish time would be the same as or before its Arrival time.

SP_END_NOT_GT_START_TIME (31) is returned if:

  • the job’s Arrival time would be earlier than its Start time, or
  • the job’s Finish time would be earlier than its Start time