Appointment

  • 15.5
This article is may not be up to date with the latest stable release of M4.

Description

The Appointment endpoint provides the API consumer with access to methods pertaining to appointments and related data objects. The endpoint allows consumers to load appointment data, add new appointments, and update appointments.

Methods

URL base/Workforce/Appointment/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to the Appointment endpoint.
Parameters None
 Returns  A JSON object with method descriptions
Sample Return Object 
[
    {
        "HttpAction": "Get",
        "MethodName": "GetAppointment",
        "Description": "Returns the record for a single appointment given the passed in ID value (see Path).",
        "Path": "/Appointment/GetAppointment/25032"
    },
    {
        "HttpAction": "Get",
        "MethodName": "GetAppointmentsByTicket",
        "Description": "Returns appointments given the passed in ID value of the ticket (see Path).",
        "Path": "/Appointment/GetAppointmentsByTicket/25032"
    },
    {
        "HttpAction": "Post",
        "MethodName": "GetAppointmentByUserIDTimeFrameTicketID",
        "Description": "Returns the record for a single appointment given the passed in User ID, Start Time, End Time, and Ticket ID values.",
        "Format": {
            "UserID": 929,
            "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
            "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
            "TicketID": 294
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "GetAppointmentsByUserIDTimeAndFrame",
        "Description": "Returns a collection of appointments given the passed in User ID, Start Time, and End Time values.",
        "Format": {
            "UserID": 361,
            "ApptStart": "2017-11-30T16:03:18.6339573-05:00",
            "ApptEnd": "2017-11-30T17:03:18.6339573-05:00"
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "AddAppointment",
        "Description": "Method allows for the adding of appointment information. The newly created appointment object is returned.  The UserID, TicketID, ApptStart, and ApptEnd  are required fields.",
        "Format": {
            "UserID": 929,
            "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
            "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
            "TicketID": 294
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "UpdateAppointment",
        "Description": "Method allows for the updating of appointment information. The updated appointment object is returned.  The UserID, TicketID, ApptStart, and ApptEnd  are required fields.",
        "Format": {
            "ID": 302,
            "UserID": 754,
            "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
            "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
            "TicketState": null,
            "TicketID": 543,
            "DispatcherID": null,
            "TicketType": null,
            "ChangedBy": null,
            "DisplayValue": "",
            "TicketCode": null,
            "ApptBlock": "",
            "CanReschedule": false,
            "Reminder": null,
            "TimeCleared": null,
            "TechTimeCleared": null,
            "ChangedApptEndTime": null,
            "LastUpdated": null,
            "RecurrenceRule": null,
            "RecurrenceParentID": null,
            "RecurrenceRuleKeyStr": "",
            "RecurrenceChildRuleKeyStr": "",
            "TimeClosed": null
        }
    },
    {
        "HttpAction": "Get",
        "MethodName": "DeleteAppointment",
        "Description": "Method allows for the deleting of appointment information.",
        "Path": "/Appointment/DeleteAppointment/25032"
    }
]
URL base/Workforce/Appointment/AddAppointment
Action POST
Description Adds the specified appointment object and returns the newly created appointment object.
Parameters
Name Required? Type Description
UserID Yes Integer The user ID of the technician
ApptStart Yes Date/Time The start date/time of the appointment
ApptEnd Yes Date/Time The end date/time of the appointment
TicketID Yes Integer The ticket ID to be associated with the appointment
TicketState No Integer The ticket state for the associated ticket
Sample JSON Package 
{
    "UserID": 929,
    "ApptStart": "2017-11-27T15:30:20.000-05:00",
    "ApptEnd": "2017-11-27T16:30:20.000-05:00",
    "TicketID": 25,
    "TicketState": 2
}
Returns A JSON Appointment object
Sample Return Object 
    [
    {
        "ID": 63,
        "UserID": 929,
        "TechID": 1,
        "ApptStart": "2017-11-27T15:30:20.000-05:00",
        "ApptEnd": "2017-11-27T16:30:20.000-05:00",
        "TicketState": 2,
        "TicketID": 25,
        "DispatcherID": 18,
        "TicketType": 5,
        "ChangedBy": null,
        "DisplayValue": "Permit Master - BH Test 02",
        "TicketCode": 259,
        "ApptBlock": "A",
        "CanReschedule": true,
        "Reminder": null,
        "TimeCleared": null,
        "TechTimeCleared": null,
        "ChangedApptEndTime": false,
        "LastUpdated": "2013-07-11T16:02:12.707",
        "RecurrenceRule": false,
        "RecurrenceParentID": null,
        "RecurrenceRuleKeyStr": "",
        "RecurrenceChildRuleKeyStr": "",
        "TimeClosed": null
    }
]
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

TicketID:
  • The TicketID must be a valid ticket in the database.
UserID:
  • The UserID must be a valid user in the database.
ApptStart/ApptEnd:
  • The ApptStart must occur before the ApptEnd date/time.
URL base/Workforce/Appointment/CancelAppointment/ID
Action GET
Description Cancels an Appointment object when given an ID of a valid appointment in the M4 database. Appointment will be updated to the cancelled status based on its configuration. If configured, the appointment will be moved to a cancel bucket user. A Canceled appointment will not be displayed to users in MTPro.  It will not block auto scheduling or optimization.  It will be visible in Workforce as a canceled appointment.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of an appointment in the M4 database.
Returns A JSON Appointment data object
Sample Return Object 
{
            "ID": 302,
            "UserID": 754,
            "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
            "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
            "TicketState": 18,
            "TicketID": 1,
            "DispatcherID": null,
            "TicketType": null,
            "ChangedBy": null,
            "DisplayValue": "",
            "TicketCode": null,
            "ApptBlock": "",
            "CanReschedule": false,
            "Reminder": null,
            "TimeCleared": null,
            "TechTimeCleared": null,
            "ChangedApptEndTime": null,
            "LastUpdated": null,
            "RecurrenceRule": null,
            "RecurrenceParentID": null,
            "RecurrenceRuleKeyStr": "",
            "RecurrenceChildRuleKeyStr": "",
            "TimeClosed": null
}
URL base/Workforce/Appointment/ClearAppointment/ID
Action GET
Description Clears an Appointment object when given an ID of a valid appointment in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of an appointment in the M4 database.
Returns A JSON Appointment data object
Sample Return Object 
{
            "ID": 302,
            "UserID": 754,
            "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
            "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
            "TicketState": 18,
            "TicketID": 1,
            "DispatcherID": null,
            "TicketType": null,
            "ChangedBy": null,
            "DisplayValue": "",
            "TicketCode": null,
            "ApptBlock": "",
            "CanReschedule": false,
            "Reminder": null,
            "TimeCleared": null,
            "TechTimeCleared": null,
            "ChangedApptEndTime": null,
            "LastUpdated": null,
            "RecurrenceRule": null,
            "RecurrenceParentID": null,
            "RecurrenceRuleKeyStr": "",
            "RecurrenceChildRuleKeyStr": "",
            "TimeClosed": null
}
URL base/Workforce/Appointment/DeleteAppointment/ID
Action GET
Description Deletes an Appointment object when given an ID of a valid appointment in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of an appointment in the M4 database.
Returns None
URL base/Workforce/Appointment/GetAppointment/ID
Action GET
Description Returns an Appointment object when given an ID of a valid appointment in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of an appointment in the M4 database.
Returns A JSON Appointment data object
Sample Return Object 
{
            "ID": 302,
            "UserID": 754,
            "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
            "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
            "TicketState": null,
            "TicketID": 543,
            "DispatcherID": null,
            "TicketType": null,
            "ChangedBy": null,
            "DisplayValue": "",
            "TicketCode": null,
            "ApptBlock": "",
            "CanReschedule": false,
            "Reminder": null,
            "TimeCleared": null,
            "TechTimeCleared": null,
            "ChangedApptEndTime": null,
            "LastUpdated": null,
            "RecurrenceRule": null,
            "RecurrenceParentID": null,
            "RecurrenceRuleKeyStr": "",
            "RecurrenceChildRuleKeyStr": "",
            "TimeClosed": null
}
URL base/Workforce/Appointment/GetAppointmentsByTicket/ID
Action GET
Description Returns a collection of Appointment objects when given an ID of a valid ticket in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a ticket in the M4 database.
Returns A JSON collection of Appointment data objects
Sample Return Object 
[
    {
        "ID": 63,
        "UserID": 1,
        "TechID": 1,
        "ApptStart": "2015-10-21T10:00:00",
        "ApptEnd": "2017-06-16T15:30:00",
        "TicketState": 1,
        "TicketID": 27,
        "DispatcherID": 18,
        "TicketType": 5,
        "ChangedBy": null,
        "DisplayValue": "Permit Master - BH Test 02",
        "TicketCode": 259,
        "ApptBlock": "A",
        "CanReschedule": true,
        "Reminder": null,
        "TimeCleared": null,
        "TechTimeCleared": null,
        "ChangedApptEndTime": false,
        "LastUpdated": "2013-07-11T16:02:12.707",
        "RecurrenceRule": false,
        "RecurrenceParentID": null,
        "RecurrenceRuleKeyStr": "",
        "RecurrenceChildRuleKeyStr": "",
        "TimeClosed": null
    },
    {
        "ID": 15724,
        "UserID": 1,
        "TechID": 1,
        "ApptStart": "2017-01-01T08:00:00",
        "ApptEnd": "2017-10-24T12:07:48.62",
        "TicketState": 1,
        "TicketID": 27,
        "DispatcherID": null,
        "TicketType": 1,
        "ChangedBy": null,
        "DisplayValue": "",
        "TicketCode": 4,
        "ApptBlock": "",
        "CanReschedule": false,
        "Reminder": null,
        "TimeCleared": null,
        "TechTimeCleared": null,
        "ChangedApptEndTime": null,
        "LastUpdated": "2017-10-24T11:07:48.427",
        "RecurrenceRule": null,
        "RecurrenceParentID": null,
        "RecurrenceRuleKeyStr": "",
        "RecurrenceChildRuleKeyStr": "",
        "TimeClosed": null
    }
]
URL base/Workforce/Appointment/GetAppointmentsByUserIDAndTimeFrame
Action POST
Description Gets a collection of appointment objects that match the user ID, start date/time and end date/time.
Parameters
Name Required? Type Description
UserID Yes Integer The user ID of the technician
ApptStart Yes Date/Time The start date/time of the appointment
ApptEnd Yes Date/Time The end date/time of the appointment
Sample JSON Package 
{
    "UserID": 929,
    "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
    "ApptEnd": "2017-11-27T16:48:20.6478021-05:00"
}
Returns A JSON collection of Appointment objects
Sample Return Object 
    [
    {
        "ID": 63,
        "UserID": 929,
        "TechID": 1,
        "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
        "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
        "TicketState": 1,
        "TicketID": 27,
        "DispatcherID": 18,
        "TicketType": 5,
        "ChangedBy": null,
        "DisplayValue": "Permit Master - BH Test 02",
        "TicketCode": 259,
        "ApptBlock": "A",
        "CanReschedule": true,
        "Reminder": null,
        "TimeCleared": null,
        "TechTimeCleared": null,
        "ChangedApptEndTime": false,
        "LastUpdated": "2013-07-11T16:02:12.707",
        "RecurrenceRule": false,
        "RecurrenceParentID": null,
        "RecurrenceRuleKeyStr": "",
        "RecurrenceChildRuleKeyStr": "",
        "TimeClosed": null
    },
    {
        "ID": 15724,
        "UserID": 929,
        "TechID": 1,
        "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
        "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
        "TicketState": 1,
        "TicketID": 45,
        "DispatcherID": null,
        "TicketType": 1,
        "ChangedBy": null,
        "DisplayValue": "",
        "TicketCode": 4,
        "ApptBlock": "",
        "CanReschedule": false,
        "Reminder": null,
        "TimeCleared": null,
        "TechTimeCleared": null,
        "ChangedApptEndTime": null,
        "LastUpdated": "2017-10-24T11:07:48.427",
        "RecurrenceRule": null,
        "RecurrenceParentID": null,
        "RecurrenceRuleKeyStr": "",
        "RecurrenceChildRuleKeyStr": "",
        "TimeClosed": null
    }
]
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

UserID:
  • The UserID must be a valid User in the database.
ApptStart/ApptEnd:
  • The ApptStart must occur before the ApptEnd date/time.
URL base/Workforce/Appointment/GetAppointmentByUserIDTimeFrameTicketID
Action POST
Description Gets the appointment object by user ID, start date/time, end date/time, ticket ID.
Parameters
Name Required? Type Description
UserID Yes Integer The user ID of the technician
ApptStart Yes Date/Time The start date/time of the appointment
ApptEnd Yes Date/Time The end date/time of the appointment
TicketID Yes Integer The ticket ID associated with the appointment
Sample JSON Package 
{
    "UserID": 929,
    "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
    "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
    "TicketID": 294
}
Returns A JSON Appointment object
Sample Return Object 
    {
        "ID": 302,
        "UserID": 929,
        "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
        "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
        "TicketState": null,
        "TicketID": 294,
        "DispatcherID": null,
        "TicketType": null,
        "ChangedBy": null,
        "DisplayValue": "",
        "TicketCode": null,
        "ApptBlock": "",
        "CanReschedule": false,
        "Reminder": null,
        "TimeCleared": null,
        "TechTimeCleared": null,
        "ChangedApptEndTime": null,
        "LastUpdated": null,
        "RecurrenceRule": null,
        "RecurrenceParentID": null,
        "RecurrenceRuleKeyStr": "",
        "RecurrenceChildRuleKeyStr": "",
        "TimeClosed": null
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

UserID:
  • The UserID must be a valid User in the database.
ApptStart/ApptEnd:
  • The ApptStart must occur before the ApptEnd date/time.
TicketID:
  • The TicketID must be a valid Ticket in the database.
URL base/Workforce/Appointment/GetNextAvailableAppointments
Action POST
Description Gets a collection of appointment objects which fit the criteria established by Workforce's technician schedule and skill set configuration.
Parameters
Name Required? Type Description
TicketID Yes Integer The ID of the ticket to which the appointments belongs.
TimeBlockType No String The time block type ("AM", "PM", etc.).
StartDate Yes DateTime The start of the date range of appointment availability.
AppointmentSlots Yes Integer The number of appointment slots.
CustomerServiceIDs No List of integers The service ID list for which the technicians are qualified.
Sample JSON Package 
{
    "TicketID": 9974,
    "TimeBlockType": "AM",
    "StartDate": "2018-10-03T00:00:00-04:00",
    "AppointmentSlots": 1,
    "CustomerServiceIDs": [
        150,
        537,
        469
    ]
}
Returns A JSON collection of Appointment data objects
Sample Return Object 
[
    {
        "ID": 63,
        "UserID": 1,
        "TechID": 1,
        "ApptStart": "2015-10-21T10:00:00",
        "ApptEnd": "2017-06-16T15:30:00",
        "TicketState": 1,
        "TicketID": 9974,
        "DispatcherID": 18,
        "TicketType": 5,
        "ChangedBy": null,
        "DisplayValue": "Permit Master - BH Test 02",
        "TicketCode": 259,
        "ApptBlock": "A",
        "CanReschedule": true,
        "Reminder": null,
        "TimeCleared": null,
        "TechTimeCleared": null,
        "ChangedApptEndTime": false,
        "LastUpdated": "2013-07-11T16:02:12.707",
        "RecurrenceRule": false,
        "RecurrenceParentID": null,
        "RecurrenceRuleKeyStr": "",
        "RecurrenceChildRuleKeyStr": "",
        "TimeClosed": null
    },
    {
        "ID": 15724,
        "UserID": 1,
        "TechID": 1,
        "ApptStart": "2017-01-01T08:00:00",
        "ApptEnd": "2017-10-24T12:07:48.62",
        "TicketState": 1,
        "TicketID": 9974,
        "DispatcherID": null,
        "TicketType": 1,
        "ChangedBy": null,
        "DisplayValue": "",
        "TicketCode": 4,
        "ApptBlock": "",
        "CanReschedule": false,
        "Reminder": null,
        "TimeCleared": null,
        "TechTimeCleared": null,
        "ChangedApptEndTime": null,
        "LastUpdated": "2017-10-24T11:07:48.427",
        "RecurrenceRule": null,
        "RecurrenceParentID": null,
        "RecurrenceRuleKeyStr": "",
        "RecurrenceChildRuleKeyStr": "",
        "TimeClosed": null
    }
]
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

TicketID:
  • The TicketID must be a valid Ticket in the database.
  • The Ticket must be assigned to a customer in the database.
StartDate:
  • The StartDate must be equal to or after the current date.
CustomerServiceIDs:
  • If specified, each ID in the list must exist as a valid customer service in the database.
TimeBlockType:
  • If specified, the TimeBlockType must exist as a valid time block. If set to null, all timeblocks that are assigned to the ticket, are checked.
URL base/Workforce/Appointment/UpdateAppointment
Action POST
Description Updates the specified appointment object and returns the updated appointment object.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the appointment.
DisplayValue Yes String The Display Value listed for the appointment.
CanOptimize Yes Boolean A boolean field (formerly "CanReschedule").
Sample JSON Package 
{
    "ID": 98,
    "DisplayValue": "New Appointment Item",
    "CanOptimize": true
}
Returns A JSON Appointment object
Sample Return Object 
{
    "ID": 98,
    "UserID": 929,
    "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
    "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
    "TicketState": null,
    "TicketID": 294,
    "DispatcherID": null,
    "TicketType": null,
    "ChangedBy": null,
    "DisplayValue": "New Appointment Item",
    "TicketCode": null,
    "ApptBlock": "",
    "CanReschedule": true,
    "Reminder": null,
    "TimeCleared": null,
    "TechTimeCleared": null,
    "ChangedApptEndTime": null,
    "LastUpdated": null,
    "RecurrenceRule": null,
    "RecurrenceParentID": null,
    "RecurrenceRuleKeyStr": "",
    "RecurrenceChildRuleKeyStr": "",
    "TimeClosed": null
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

ID:
  • The ID must be a valid appointment in the database.
  • The appointment has to be assigned to a technician.
  • The appointment has to be assigned to a ticket.
URL base/Workforce/Appointment/UpdateAppointmentStatus
Action POST
Description Updates the status for the specified appointment and returns the newly updated appointment data object.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the appointment.
TicketStatusID Yes Integer The ID of the ticket status.
Sample JSON Package 
{
    "ID": 98,
    "TicketStatusID": 12    
}
Returns A JSON Appointment object
Sample Return Object 
{
    "ID": 98,
    "UserID": 929,
    "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
    "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
    "TicketState": 12,
    "TicketID": 294,
    "DispatcherID": null,
    "TicketType": null,
    "ChangedBy": null,
    "DisplayValue": "",
    "TicketCode": null,
    "ApptBlock": "",
    "CanReschedule": false,
    "Reminder": null,
    "TimeCleared": null,
    "TechTimeCleared": null,
    "ChangedApptEndTime": null,
    "LastUpdated": null,
    "RecurrenceRule": null,
    "RecurrenceParentID": null,
    "RecurrenceRuleKeyStr": "",
    "RecurrenceChildRuleKeyStr": "",
    "TimeClosed": null
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

ID:
  • The ID must be a valid appointment in the database.
  • The appointment has to be assigned to a technician.
  • The appointment has to be assigned to a ticket.
  • The ticket assigned to the appointment, must be assigned to a ticket code.
  • The ticket code assigned to the appointment ticketm must be assigned to a ticket type.
TicketStatusID:
  • The TicketStatusID must be a valid ticket status in the database.
  • The ticket status must match the transition template of the appointment ticket.
  • The status cannot be a reserved status ["Cancelled", "Clearing" or "Cleared"]. These statuses have distinct workflows and cannot be changed via this API method.
  • A status transition must be defined for the specified ticket status.
URL base/Workforce/Appointment/AddClearCodeToAppointment
Action POST
Description This method assigns a Ticket Clear Code to an existing appointment/schedule.
Parameters
Name Required? Type Description
ScheduleID Yes Integer The ID of an appointment/schedule in the M4 database.
TicketClearCodeID Yes Integer The ID of a Ticket Clear Code in the M4 database.
Sample JSON Package 
{ 
    "ScheduleID": 160, 
    "TicketClearCodeID": 1 
}
Returns A Ticket Clear Code JSON data object representing the newly assigned clear code.
Sample Return Object 
{ 
    "ID": 1, 
    "TicketClearCodeType": 1, 
    "Description": "Trouble Ticket Clear Code" 
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

ScheduleID:
  • The ScheduleID must link to a valid appointment/schedule in the database.
  • The appointment/schedule must be linked to a valid ticket.
  • The ticket assigned to the appointment/schedule must be linked to a ticket code.
TicketClearCodeID:
  • The TicketClearCodeID must link to a valid ticket clear code in the database.
  • The ticket clear code must be allowed for the ticket assigned to the appointment/schedule.
  • The ticket clear code must not already be assigned to the appointment/schedule.
  • The ticket clear code type for the clear code must not already be assigned to the appointment/schedule.
URL base/Workforce/Appointment/DeleteClearCodeFromAppointment
Action POST
Description This method removes a Ticket Clear Code assigned to an existing appointment/schedule.
Parameters
Name Required? Type Description
ScheduleID Yes Integer The ID of an appointment/schedule in the M4 database.
TicketClearCodeID Yes Integer The ID of a Ticket Clear Code in the M4 database.
Sample JSON Package 
{ 
    "ScheduleID": 160, 
    "TicketClearCodeID": 1 
}
Returns A JSON system message object stating that the removal action was successful.
Sample Return Object 
{ 
    "Message": "The ticket clear code associated with the specified appointment/schedule was deleted successfully." 
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

ScheduleID:
  • The ScheduleID must link to a valid appointment/schedule in the database.
TicketClearCodeID:
  • The TicketClearCodeID must link to a valid ticket clear code in the database.
  • The ticket clear code must already be assigned to the appointment/schedule.
URL base/Workforce/Appointment/ScheduleAppointment
Action POST
Description Schedules an appointment object which fit the criteria established by Workforce's technician schedule and skill set configuration for the specified time-block on hold.
Parameters
Name Required? Type Description
TicketID Yes Integer The ID of the ticket
ApptID Yes Integer The ID of the appointment
Sample JSON Package 
{
	"TicketID": 98,
	"ApptID": 487
}
Returns A JSON Appointment data object
Sample Return Object 
{
       "ID":487,
       "UserID":3,
       "TechID":3,
       "ApptStart":"2019-07-26T08:00:00",
       "ApptEnd":"2019-07-26T08:30:00",
       "TicketState":19,
       "TicketID":98,
       "DispatcherID":null,
       "TicketType":1,
       "ChangedBy":null,
       "DisplayValue":"12934cb6-1994-4f1b-87d0-6c6e82e644cb",
       "TicketCode":1,
       "ApptBlock":"A",
       "CanReschedule":true,
       "Reminder":null,
       "TimeCleared":null,
       "TechTimeCleared":null,
       "ChangedApptEndTime":false,
       "LastUpdated":"2019-07-24T11:13:55.14",
       "RecurrenceRule":false,
       "RecurrenceParentID":null,
       "RecurrenceRuleKeyStr":"",
       "RecurrenceChildRuleKeyStr":"",
       "TimeClosed":null
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • TicketID: must be an existing ticket.
  • ApptID: must be an existing appointment.
URL base/Workforce/Appointment/RescheduleAppointment
Action POST
Description Reschedules an appointment with a new start or end date/time, technician and dispatcher.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the appointment.
TechID Yes Integer The user ID of the technician.
ApptStart Yes Date/Time The start date/time of the appointment
ApptEnd Yes Date/Time The end date/time of the appointment
DispatcherID No Integer The user ID of the dispatcher.
Sample JSON Package 
    {
        "ID": 103,
        "TechID": 929,
        "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
        "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
        "DispatcherID": 43,
    }
Returns A JSON Appointment object
Sample Return Object 
{
    "ID": 103,
    "UserID": 929,
    "ApptStart": "2017-11-27T15:48:20.6478021-05:00",
    "ApptEnd": "2017-11-27T16:48:20.6478021-05:00",
    "TicketState": 12,
    "TicketID": 294,
    "DispatcherID": 43,
    "TicketType": null,
    "ChangedBy": null,
    "DisplayValue": "",
    "TicketCode": null,
    "ApptBlock": "",
    "CanReschedule": false,
    "Reminder": null,
    "TimeCleared": null,
    "TechTimeCleared": null,
    "ChangedApptEndTime": null,
    "LastUpdated": null,
    "RecurrenceRule": null,
    "RecurrenceParentID": null,
    "RecurrenceRuleKeyStr": "",
    "RecurrenceChildRuleKeyStr": "",
    "TimeClosed": null
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

ID:
  • The ID must be a valid appointment in the database.
  • The appointment has to be assigned to a ticket.
  • The ticket assigned to the appointment, must be assigned to a ticket code.
  • The ticket code assigned to the appointment ticketm must be assigned to a ticket type.
TechID:
  • The tech ID must be a valid user in the database.
DispatcherID:
  • The dispatcher ID must be a valid user in the database.
ApptStart/ApptEnd:
  • The ApptStart must occur before the ApptEnd date/time.
  • The appointment time frame window must be a minimum of 30 minutes.
Reschedule Only Allowed if:
  • The assigned ticket status must allow the appointment to be rescheduled.
  • Fields can only be changedif there is a legitimate update (i.e. technician has changed or the appointment start/end date/time has changed).

Was this article helpful?

Yes No

Related Articles