Appointment

The appointmentAppointmentA task scheduled to a resource for a specific period - the scheduled instance you see on the planning board. entity is what Dime.Scheduler is all about. An appointment is the main deliverable of the software and represents a block in the planning boardPlanning boardThe main graphical scheduling surface where dispatchers drag tasks onto resources across a timeline.. The appointment contains the information of the appointment such as the start and end date, and it holds references to the resourcesResourceAn entity that can carry out work - a person, vehicle, tool, or room - that you schedule on the planning board. that have been assigned to it.

The following entities are exposed through the API.

Appointment

Upsert appointment

Inserts or updates an appointment record. The behavior of this procedure depends on the data you pass to it:

• The appointment id is required if you want to update an existing appointment.
• Otherwise, it inserts an appointment resource record (linking a resource to the appointment) if the record does not exist.

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)		✔️	See API reference
SourceType	nvarchar(10)		✔️	See API reference
JobNo	nvarchar(50)		✔️
TaskNo	nvarchar(50)		✔️
AppointmentNo	nvarchar(max)	0
AppointmentId	bigint	0
Subject	nvarchar(max)
Body	nvarchar(max)
Start	datetime			Use ISO 8601 format: yyyy-mm-ddThh:mm
End	datetime			Use ISO 8601 format: yyyy-mm-ddThh:mm
IsAllDayEvent	bit	0		This field is deprecated.
Category	nvarchar(100)			See API reference
TimeMarker	nvarchar(100)			See API reference
Tags	nvarchar(1000)			See API reference
Importance	int	0		See API reference
Locked	bit	0
ResourceNo	nvarchar(50)
AppointmentGuid	nvarchar(50)
ReplaceResource	bit	0
SentFromBackOffice	bit	1
BackofficeID	nvarchar(100)
BackofficeParentID	nvarchar(100)
PlanningUOM	nvarchar(20)
PlanningUOMConversion	decimal(18,6)	0
PlanningQty	decimal(18,6)	0
UseFixPlanningQty	bit	0
RoundToUOM	bit	0
Preamble	int			See API reference
Postamble	int			See API reference
NonWorkingTime	float			See API reference
Progress	int			See API reference
IsManualAppointment	bit	0		See API reference

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_upsertAppointment.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_upsertAppointment",
          "ParameterNames": ["SourceApp", "SourceType", "JobNo", "TaskNo", "Subject", "Start", "End"],
          "ParameterValues": ["BCCOMPANY1", "JOB", "JOB001", "TASK001", "Important meeting", "2024-01-01T15:00","2024-01-02T15:00"]
      }
  ]

API

• See POST /appointment, PUT /appointment in the REST API reference.
• Example body:

  {
    "SourceApp": "BCCOMPANY1",
    "SourceType": "JOB",
    "JobNo": "JOB001",
    "TaskNo": "TASK001",
    "AppointmentNo": "xj0rJJb3",
    "Start": "2024-01-01T15:00",
    "End": "2024-01-02T15:00",
    "Subject": "Important meeting"  
  }

Delete appointment

The behavior of this procedure depends on the data you pass to it:

• If a resource number is provided, then the appointment resource record is deleted. The appointment record is also deleted if no more appointment resource records exist for the appointment.
• If the resource number is not provided, then the appointment record and all linked appointment resource records are deleted.

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)		✔️	See API reference
SourceType	nvarchar(10)		✔️	See API reference
AppointmentNo	nvarchar(max)	0
AppointmentId	bigint
AppointmentGuid	nvarchar(50)
ResourceNo	nvarchar(50)
SentFromBackOffice	bit	1

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_deleteAppointment.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_deleteAppointment",
          "ParameterNames": ["SourceApp", "SourceType", "AppointmentNo"],
          "ParameterValues": ["BCCOMPANY1", "JOB", "x0rnJJ2b"]
      }
  ]

API

See DELETE /appointment in the REST API reference.

Upsert appointment URI

Inserts or updates an appointment URI record.

An appointment URI contains links to documents, web pages and the back-office system. You need to pass an existing appointment id or appointment GUID.

Name	Data Type	Default	Required	Description
pSourceApp	nvarchar(30)			See API reference
pSourceType	nvarchar(10)			See API reference
pAppointmentId	bigint	0
pAppointmentGuid	nvarchar(50)
pUrl	nvarchar(1000)		✔️
pUrlDesc	nvarchar(255)

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_upsertAppointmentUrl.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_upsertAppointmentUrl",
          "ParameterNames": ["pUrl", "pAppointmentId"],
          "ParameterValues": ["https://docs.dimescheduler.com", "15123"]
      }
  ]

API

See POST /appointmentUri, PUT /appointmentUri in the REST API reference.

Appointment container

A containerContainerA grouping mechanism that bundles related tasks or appointments so planners can move and manage them together. groups records so the planner can move them as one. Putting an appointment in a container is a separate record from the appointment itself, which is why it has its own upsert and delete: the container keeps existing when the appointment leaves it, and the appointment keeps existing when it is taken out of the container. See containers for the container records themselves.

Upsert appointment container

Adds or updates the allocation of an appointment to a container.

Name	Data Type	Default	Required	Description
Container	nvarchar(100)		✔️	Name of the container
Appointment	nvarchar(100)		✔️	Appointment GUID or AppointmentNo

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_upsertAppointmentContainer.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_upsertAppointmentContainer",
          "ParameterNames": ["Container", "Appointment"],
          "ParameterValues": ["CONTAINER001", "200"]
      }
  ]

API

• See POST /appointmentContainer, PUT /appointmentContainer in the REST API reference.
• Example body:

  [
      {
          "container": "Container 1",
          "appointment": "ad37cfba-f502-4592-883d-4b10433722fe"
      },
      {
          "container": "Container 1",
          "appointment": "ad37cfba-f502-4592-883d-4b10433722ff"
      }
  ]

• Note: The appointment field accepts either an appointment GUID or AppointmentNo.

Delete appointment container

Takes an appointment out of a container. Both the appointment and the container are left untouched.

Name	Data Type	Default	Required	Description
Container	nvarchar(100)		✔️	Name of the container
Appointment	nvarchar(100)			Appointment GUID or AppointmentNo
AppointmentId	bigint	0		Internal appointment id

Identify the appointment with either Appointment or AppointmentId; leaving both empty is rejected with REQ002. The container must exist (DATA012) and so must the appointment (DATA005).

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_deleteAppointmentContainer.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_deleteAppointmentContainer",
          "ParameterNames": ["Container", "Appointment"],
          "ParameterValues": ["CONTAINER001", "200"]
      }
  ]

API

See DELETE /appointmentContainer in the REST API reference.

Add assignment

Add a resource to an existing appointment, thereby creating a linked appointment.

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)			See API reference
SourceType	nvarchar(10)			See API reference
AppointmentId	bigint		✔️
AppointmentNo	nvarchar(max)	0
ResourceNo	nvarchar(50)		✔️
AppointmentGuid	nvarchar(50)
SentFromBackOffice	bit	1

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_addAppointmentResource.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_addAppointmentResource",
          "ParameterNames": ["AppointmentId", "ResourceNo"],
          "ParameterValues": ["100", "2"]
      }
  ]

API

See POST /assignment, PUT /assignment in the REST API reference.

Properties

Update appointment content

Updates the body and subject of the selected appointment.

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)			See API reference
SourceType	nvarchar(10)			See API reference
AppointmentId	bigint
AppointmentNo	nvarchar(max)	0
AppointmentGuid	nvarchar(50)
SentFromBackOffice	bit	1
Subject	nvarchar(max)
Body	nvarchar(max)

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_updateAppointmentContent.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_updateAppointmentContent",
          "ParameterNames": ["AppointmentId", "Subject"],
          "ParameterValues": ["1", "Hello world!"]
      }
  ]

API

See POST /appointmentContent in the REST API reference.

Update appointment planning quantity

Updates the planning quantityPlanning quantityThe amount of work an appointment represents, by default its duration in hours. A conversion factor can express it in another unit, and the capacity view compares it against resource load. of an appointment.

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)			See API reference
SourceType	nvarchar(10)			See API reference
AppointmentId	bigint
AppointmentNo	nvarchar(max)	0
PlanningQty	decimal(18,6)
AppointmentGuid	nvarchar(50)
SentFromBackOffice	bit	1

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_updateAppointmentPlanningQty.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_updateAppointmentPlanningQty",
          "ParameterNames": ["AppointmentId", "PlanningQty"],
          "ParameterValues": ["1", "24"]
      }
  ]

API

See POST /appointmentPlanningQuantity in the REST API reference.

Indicators

Set time marker

Update the time markerTime markerA visual indicator on an appointment, separate from its category, used to flag a status or condition at a point in time. assigned to the appointment. Can be used to update status or progress of the appointment.

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)			See API reference
SourceType	nvarchar(10)			See API reference
AppointmentId	bigint
AppointmentNo	nvarchar(max)	0
TimeMarker	nvarchar(100)
AppointmentGuid	nvarchar(50)
SentFromBackOffice	bit	1

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_updateAppointmentTimeMarker.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_updateAppointmentTimeMarker",
          "ParameterNames": ["AppointmentId", "TimeMarker"],
          "ParameterValues": ["1", "TIMEMARKER002"]
      }
  ]

API

See POST /appointmentTimeMarker in the REST API reference.

Set category

Updates the categoryCategoryA visual indicator (a color) applied to appointments to classify or label them. assigned to the appointment. Can be used to update status or progress of the appointment.

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)			See API reference
SourceType	nvarchar(10)			See API reference
AppointmentId	bigint
AppointmentNo	nvarchar(max)	0
Category	nvarchar(100)
AppointmentGuid	nvarchar(50)
SentFromBackOffice	bit	1

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_updateAppointmentCategory.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_updateAppointmentCategory",
          "ParameterNames": ["AppointmentId", "Category"],
          "ParameterValues": ["1", "CATEGORY002"]
      }
  ]

API

See POST /appointmentCategory in the REST API reference.

Field values

Sets the field value of an appointment

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)			See API reference
SourceType	nvarchar(10)			See API reference
AppointmentId	bigint
AppointmentNo	nvarchar(max)	0
AppointmentGuid	nvarchar(50)
FieldCode	nvarchar(100)	0
FieldValue	nvarchar(MAX)	1
SentFromBackOffice	nvarchar(MAX)	1

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_updateAppointmentFieldValues.
• Example body:

  [
    {
        "StoredProcedureName": "mboc_updateAppointmentFieldValues",
        "ParameterNames": ["AppointmentId","FieldCode","FieldValue"],
        "ParameterValues": ["1","FINISHED","true"]
    }
  ]

API

See POST /appointmentFieldValue, PUT /appointmentFieldValue in the REST API reference.

Set importance

Sets the importanceImportanceA fixed scale driven by the back office, shown as an exclamation mark or arrow at the start of the appointment bar. What it stands for (priority, urgency) is decided when the application is set up. of an appointment.

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)			See API reference
SourceType	nvarchar(10)			See API reference
AppointmentId	bigint
AppointmentNo	nvarchar(max)	0
Importance	int	0		See API reference
AppointmentGuid	nvarchar(50)
SentFromBackOffice	bit	1

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_updateAppointmentImportance.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_updateAppointmentImportance",
          "ParameterNames": ["AppointmentNo", "Importance"],
          "ParameterValues": ["ZVELNXY4", "1"]
      }
  ]

API

See POST /appointmentImportance in the REST API reference.

Set lock

Locks or unlocks a single appointment. A locked appointmentLocked appointmentAn appointment that cannot be moved or edited. The lock is set in the back office, not in Dime.Scheduler, and locked appointments are drawn with shaded stripes. can not be modified nor deleted on the planning board. The task has the same operation for all appointments of a task at once; use this one when only one of them must be frozen, for instance because the customer confirmed that visit and not the others.

Name	Data Type	Default	Required	Description
SourceApp	nvarchar(30)			See API reference
SourceType	nvarchar(10)			See API reference
AppointmentId	bigint
AppointmentNo	nvarchar(max)	0
Locked	bit	0
AppointmentGuid	nvarchar(50)
SentFromBackOffice	bit	1

Identify the appointment with AppointmentId, AppointmentNo or AppointmentGuid. An appointment that does not exist is not reported as an error: the request is accepted and nothing changes, so check the identifier when a lock does not seem to stick.

Import

• This endpoint is available in the import API endpoint /import via the procedure mboc_updateAppointmentLocked.
• Example body:

  [
      {
          "StoredProcedureName": "mboc_updateAppointmentLocked",
          "ParameterNames": ["SourceApp", "SourceType", "AppointmentNo", "Locked"],
          "ParameterValues": ["BC", "Job", "ZVELNXY4", "true"]
      }
  ]

API

See POST /appointmentLocked in the REST API reference.

Appointment dependency

A dependency says that one appointment constrains another: the second cannot be placed freely because it is tied to the first. The Gantt chartGantt chartA timeline view for long-term project planning, showing tasks, durations, dependencies and milestones. draws dependencies as links between the two blocks and uses them to work out the order of a projectProjectA job seen as a whole in project planning: a body of work with a budget, a team, dependencies and a deadline. Its tasks are still planned as ordinary appointments on the board.. This is the appointment-level counterpart of the task dependency: a task dependency describes how the work relates, an appointment dependency ties two concrete blocks on the board together.

Dependencies are available through the REST API only; there is no import procedure.

Name	Data Type	Default	Required
id	int
fromAppointmentGuid	string (uuid)
fromAppointmentNo	string
toAppointmentGuid	string (uuid)
toAppointmentNo	string
type	int
lag	int
lagUnit	string

The dependency runs from the first appointment to the second: from is the predecessor, to is the appointment that depends on it. Identify each end with either its GUID or its AppointmentNo; an end with neither is rejected with REQ002, a GUID that does not exist with DATA005, and an AppointmentNo that cannot be decoded with REQ005. type, lag and lagUnit have the same meaning as on a task dependency.

Unlike the task dependency, an appointment dependency is identified by the id the create call returns, not by the pair of appointments. Pass that id to update or delete it; both are rejected with REQ002 without it.

API

• See GET /appointmentDependency, POST /appointmentDependency, PUT /appointmentDependency and DELETE /appointmentDependency in the REST API reference.
• GET /appointmentDependency returns every dependency of the tenant, each with its id, both appointments and the type, lag and lag unit.
• Example body for POST /appointmentDependency:

  {
      "fromAppointmentGuid": "ad37cfba-f502-4592-883d-4b10433722fe",
      "toAppointmentGuid": "ad37cfba-f502-4592-883d-4b10433722ff",
      "type": 2
  }

• Example body for DELETE /appointmentDependency:

  {
      "id": 42
  }

Read

Two REST endpoints read appointments back; there is no import procedure for reading. GET /appointment returns the appointments of the given resources within a date range: pass startDate, endDate and one or more resource numbers in resources. The resources parameter is required, and a request without it is answered with 400 Bad Request rather than an empty list. GET /appointment/{id} returns one appointment and accepts the numeric appointment id, the AppointmentNo or the appointment GUID; the kind of identifier is detected from the value. See the REST API reference.

API reference

Source

Dime.Scheduler is a centralized planning application. One of its key tenets is the ability to accommodate data from different origins. For instance, it is perfectly acceptable to plan work orders from Business Central, CRM, imported Excel sheets, etc., and Dime.Scheduler won't break a sweat because of the existence of the Source App and Source Type fields in the data model.

Source App

When the planner creates an appointment for a resource or task, Dime.Scheduler knows which system to notify. Through the connector setup, Dime.Scheduler will find a matching SourceApp and subsequently send the appointment to the corresponding URI.

The source appSource appAn identifier Dime.Scheduler attaches to data so it can route a change back to the correct back-office system. field is a unique identifier that identifies a back-officeBack officeThe ERP or business system Dime.Scheduler plans for - most often Microsoft Dynamics 365 Business Central. It owns the master data and remains authoritative over what it receives. instance such as a tenant of Business Central, a test environment, an instance of CRM cloud, or any other application you wish to use to feed data into Dime.Scheduler.

Back officeERP · CRM · LoB

served bySource App

ConnectorBound to one Source App

creates

JobProject container

contains

TaskWork to do

scheduled as

AppointmentPlanning decision

Step 1 of 4Back office Connector

The back office is bound to a connector

Each back-office instance - a Business Central tenant, a CRM environment, an Excel sheet - is identified by a Source App. The connector is configured for that one Source App and nothing else, so Dime.Scheduler always knows which system any record came from.

Source Type

The SourceType is used inside the back-office system itself. A source typeSource typeAn identifier that, together with the source app, tells Dime.Scheduler which back-office table a record belongs to. represents a distinct entity such as a service orderService orderA Business Central service management document. The service order solution plans it as one task or as one task per service item line, and writes the assignment back as a resource allocation., production orderProduction orderA Business Central manufacturing order with routing lines. The production routing solution puts those lines on the planning board against work and machine centers while BC’s own rules still hold., assembly orderAssembly orderA Business Central document that says what to build. The assembly order solution schedules the resources that build it and keeps the order’s dates in sync., etc.

The standard connectorsConnectorAn integration that links Dime.Scheduler to a back-office system, routing data in and scheduling decisions back out. that Dime Software provides make it possible to plan different types of resources and tasks. When Dime.Scheduler posts an appointment to a standard connector, it ends up in a staging tableStaging tableThe Dime.Scheduler Appointments table in Business Central where incoming appointments land first. Business Central processes rows from there, so a row can be received and still fail processing., which is then processed by the connector to ensure the appointment produced in Dime.Scheduler is traced back to the original record using the externally identifiable fields (JobNo, TaskNo, ResourceNo) that identify the record.

Category

Controls the visual indicator of the planned task in the planning board. Read more about categories.

Time Marker

Controls the visual indicator of the planned task in the planning board. Read more about time markers.

Tags

Preview

Tags are currently in preview. Functionality and behavior may change between releases.

A semicolon-delimited list of tag codes, for example URGENT;NIGHTSHIFT. An appointment can carry as many tags as fit within the 1000 characters, and each one renders as an icon badge on the appointment bar.

Omitting the parameter and sending an empty value mean different things:

• Omitted (NULL) means "not provided". The stored tags are kept, so a connector that knows nothing about tags never wipes the tags a planner set by hand.
• Empty string means "no tags", and clears them.

An appointment created from a task starts out with that task's tags, after which the two are independent. Read more about tags.

Travel time

Preamble is the travel or preparation time before an appointment starts, and Postamble the travel or wrap-up time after it ends. Both are expressed in seconds.

They are not part of the appointment's duration: the appointment still starts and ends when its dates say it does. The preamble and postamble describe the time around it that the resource is nonetheless occupied, which is what lets the planning board show a drive in front of a job and warn when two jobs are too far apart to be done back to back.

Dime.Scheduler writes these itself when a planner calculates travel timeTravel timeThe time needed to get from one appointment to the next, calculated from their locations. The planning board can show it in front of each appointment and fold it into the schedule.. Send them from the back office when it is the system that knows how long the trip takes.

Non-working time

NonWorkingTime is time inside the appointment's own window during which no work happens, expressed in seconds. A lunch break in the middle of a full-day job is the usual case.

It matters because it is subtracted from the duration when the planning quantity is calculated. An eight hour appointment with 1800 seconds of non-working time consumes seven and a half hours of the resource's capacityCapacityThe amount of working time a resource has available in a given period, used to spot over- and under-planning., not eight.

Progress

Progress is how far the appointment's work has come, as a percentage from 0 to 100. A value outside that range is rejected with REQ005. Omit it to keep the stored value.

Manual appointment

Set this flag to true to create a manual appointment. Manual appointments don't require a job and task.