1. Integrating with Inbound API
  2. ‘appointment’ Structure

‘appointment’ Structure

The 'appointment' structure contains activity properties to be processed by the Inbound API, including activity fields, properties of the customer inventory assigned to the activity, its company-specific properties, its file properties and data on activities linked to it.
Note:

Please note, that there are 4 fields available in 'appointment' structure through SDK, that are intended for storing and proper processing of activity address information:

- 'address' (should contain street and building reference. Should not contain the information for which the dedicated fields are present (city, state, zip), or which is not relevant to activity location).

Not following the rules of fields mapping (like putting all address data into single field, including additional information like "flr. 5, appt. 25, knock 3 times and call Bob") will most likely lead to difficulties with further geocoding and routing processes inside OFSC.

Fields visibility is specified separately for each company user. The 'appointment' structure is an array of 'appointment' nodes that can contain the following elements (if no default value is defined in the table, the element by default will be empty):

'appointment' structure elements

Name

Type

Description

address

string (100)

customer's address

appt_number

string (40)

ID of the activity in client system

action_if_completed

enum

'action_if_completed' parameter, defines the way non-pending properties are processed.

Please see section 'action_if_completed' Meanings for details.

default value: 'head/appointment/action_if_completed' or its default

cell

regexp

valid customer's cell phone

city

string (40)

customer's city of residence

coordx

float

(64bit double)

longitude of customer's location

coordy

float

(64bit double)

latitude of customer's location

customer_number

string (40)

customer's account number

email

regexp

customer's valid email address

duration

integer

[0 - 65535]

defines duration ('length') of activity in minutes.

Mandatory for 'insert_appointment'.

language

string

company-specific language ID or country code top-level domain (ccTLD). If the value is numeric it is treated as integer language ID, else it is treated as CCTLD.

default value: resource's language ID

name

string

optional

customer's name

points

integer

[0 - 65535]

optional

meaningful for 'update_activity', 'cancel_activity' and 'delete_activity' and is used in Quota Management and Routing

default value: 0 (please set visibility to mandatory if this default is not acceptable)

phone

regexp

valid customer's regular phone number

reminder_time

integer

customer's reminder notification time: minutes before the start of the activity about which the customer is to be notified. The valid values are defined in the process of implementation.

service_window_start

time

service window start time in HH:MM format

default value: If the 'Support of Time Slots' feature is enabled for the activity type, then these fields are ignored and 'time_slot' is used instead, otherwise these fields are used to set the service window.

Either none or both fields must be present – specifying only one results in error.

service_window_end

time

sla_window_start

datetime

start of time when the activity can be performed without an SLA loss

YYYY-MM-DD HH:MM format

sla_window_end

datetime

end of time when the activity can be performed without an SLA loss

YYYY-MM-DD HH:MM format

state

regexp

customer's state, one of valid state values

team_id

string

external identifier of the team-holder

Mandatory for 'insert_appointment' if activity type is teamwork, otherwise it is ignored.

time_slot

enum

If the 'Support of Time Slots' feature is enabled for the activity type, then 'time_slot' field is mandatory (command rejected if absent).

If the 'Support of Time Slots' feature is disabled for the activity type, then 'time_slot' field must not be present (command rejected if present).
access_schedule

string

 Access Schedule defines the schedule (that is, the set of time intervals/access hours, two intervals per week day) when the asset or the activity location is accessible. Work should be started and finished during the same Access Schedule interval. Performing the work beyond Access Hours is generally not possible.

This field is a string, which contains an inner json object (encoded as a string). The maximum length of this field is 1020 bytes.

For example:

<access_schedule>{"schedule":[ {"weekdays":["Mon","Tue","Wed","Thu","Fri"],"hours":[["12:00","12:30"],["13:00","18:00"]]},{"weekdays":["Sat","Sun"],"hours":[["12:00","15:00"]]} ],"exceptDates":["2016-01-01","2017-01-02","2017-01-01","2017-01-02"]}</access_schedule>

The inner json object has the following schema: 
{
"type":"object",
	"properties":{
		"schedule":{
			"type":"array",
				"items":{
			"type":"object",
					"properties":{
						"daysOfWeek":{
						"type":"array",
						"items":
							{ "type":"string", 
							"enum":["Mon","Tue","Wed","Thu","Fri","Sat","Sun"] }
},
	"hours":{
		"type":"array",
			"items":{
				"type":"array",
			"items":
				{ "type":"string" }
}
}
}
}
},
	"exceptDates":{
		"type":"array",
		"items":
			{ "type":"string" }
}
}
}
time_zone

enum

time zone ID or time zone name

If the value passed in the time zone field is numeric it is treated as integer time zone ID, else it is treated as time zone name

default value: resource's time zone ID

worktype

enum

activity type id and label of the worktype

only one of the two must be present (mandatory)

worktype_label

enum

zip

regexp

optional; valid zip code

customer's zip/post code; depends on company's rules for zip codes

inventories

struct

array of 'inventory' structures containing activity inventories

properties

struct

array of 'property' structures containing activity properties

provider_preferences

struct

array of 'preference' structures the define resources preferred, required or forbidden for the activity

When empty, the existing preferences are deleted.

userdata

string

string that is returned in SOAP response without change, not used by Inbound Interface, intended for client use (e.g. to store an ID in SOAP request and quickly find record in SOAP response using this ID)

files

struct

array of 'file' structures containing activity file properties

links

struct

array of 'link' structures each describing a link between the current activity and another activity

required_inventories

struct

array of 'required_inventory' structures that define the inventories required for the activity

  • 'appointment' Structure Example

<appointment> 
			<appt_number>0001</appt_number> 
			<customer_number>Customer_number N85</customer_number> 
			<worktype>11</worktype> 
			<worktype_label>DEI</worktype_label> 
			<service_window_start>8:00</service_window_start> 
			<service_window_end>19:00</service_window_end> 
			<name>name</name> 
			<phone>11111111</phone> 
			<email>test@test.com</email> 
			<cell>11111111</cell> 
			<address>address</address> 
			<city>city</city> 
			<zip>11111</zip> 
			<state>CA</state> 
			<points>234</points> 
			<language>1</language> 
			<daybefore_flag>0</daybefore_flag> 
			<reminder_time>0</reminder_time> 
			<time_zone>2</time_zone> 
			<properties> 
				<property> 
					<label>MAP_GRID</label> 
						<value>AA11</value> 
			</property> 
		</properties> 
		<userdata>12345 
	</userdata> 
</appointment>