Skip to main content

Using the SDK

Usage​

After installing the SDK, import the namespace where all the functionality lives:

using Dime.Scheduler;
using Dime.Scheduler.Entities;

Now you can easily access the DimeSchedulerClient class. To get started, you only need an API key:

// For production:
DimeSchedulerClient client = new("mykey");

// For sandbox:
DimeSchedulerClient client = new("mykey", Environment.Sandbox);
Quick link

To create an API key, continue here.
For the sandbox environment, continue on this page.

This object exposes all the endpoints which you can interact with.

There are two ways to get data into Dime.Scheduler via the SDK: through the low-level import API, or through the direct endpoints. Either way, the classes that you will interact with to get data into the system are simple POCOs, decorated by internal mapping and validation information. Behind the covers, these POCOs are translated to a type which the API in Dime.Scheduler can interpret and execute. The API in Dime.Scheduler itself too is a simple and extensible framework which can be customized to your customer's needs.

This example adds or updates a category through the import pipeline:

Category category = new("Category #1", "#5246CE");

DimeSchedulerClient client = new("mykey");
await client.Indicators.Categories.CreateAsync(category);

This example adds or updates a filter group:

FilterGroup filterGroup = new FilterGroup { Name = "Group 1" };

DimeSchedulerClient client = new("mykey");
await client.Filters.Groups.CreateAsync(filterGroup);

As you can see, the experience is exactly the same. The only thing you need to worry about is the (correctness of the) data.

Endpoints​

By far the easiest approach is to use the direct endpoints. Each entity type has its own dedicated endpoint which you can invoke. For instance, to create a category, one of the visual indicators to render the background color of appointments, this is what you'd need to do:

DimeSchedulerClient client = new("mykey");
await client.Indicators.Categories.Create(new("Category #1", "#5246CE"));

Below is the list of endpoints that are available in the DimeSchedulerClient class. The top level displays the endpoint in SDK and its root entity, if there are no subsequent levels. If there are dependent entities, they are displayed below the root entity. As such, it is possible that an endpoint may accept more than one model, such as those that target specific properties of a root entity such as an appointment. For example, the AppointmentLocked class is a dependent entity of the Appointment class, and as such the data must be passed to the Appointments endpoint in the SDK.

tip

For the full list of the (required) properties, check out the API reference docs, or check out the check out the source code.

  • ActionUri: invoke HTTP GET or POST requests on tasks and appointments.
  • Caption: Override the standard localization
  • Indicators
    • Category: Background color of appointments
    • TimeMarker: Underscore bar of appointments
    • Pin: Color of markers on the map
  • Connector: Send planning data back to your backoffice system
  • Container: Group tasks and appointments
  • Filters: Find suitable resources for the task at hand
    • FilterGroup
    • FilterValue
  • Message: Send transient messages to the active users
  • Notification: Persistent messages for tasks, appointments, jobs, or just a general message for everybody.
  • Resource: The entity that can be planned. Can also be set:
    • ResourceFilterValue: Assign a filter value to this resource.
    • ResourceCalendar: Assign a calendar to a resource for a given date range.
    • ResourceCapacity: Used in the capacity pivot.
    • ResourceGpsTracking: Update the current location of the resource.
    • ResourceCertificate: obsolete
    • ResourceUri: Add a link to relevant documentation about this resource.
  • Job: The parent entity of a task that contains data such as customer and contact info, addresses, etc.
  • Task: The unit of work that needs to be planned. Can also be set:
    • TaskFilterValue: Set requirements (i.e. filter value) for this task that a resources must contain to successfully execute the task.
    • TaskLocked: Lock/unlock appointments for this task.
    • TaskUri: Add a link to relevant documentation about this task.
    • TaskContainer: Link tasks via a container.
  • Appointment: assigment of a task to a resource on a certain date and time. Can also be set:
    • AppointmentCategory: Change the background color
    • AppointmentContent: Change subject and body
    • AppointmentLocked: Lock/unlock appointment on the planning board
    • AppointmentTimeMarker: Change color of horizontal bar at the bottom
    • AppointmentUri: Add a link to relevant documentation about this planned task
    • AppointmentContainer: Link appointments via a container
    • Assignment: Add/remove resources
    • AppointmentImportance: Change the priority of the appointment
    • AppointmentPlanningQuantity: Change the plannning quantity
    • AppointmentFieldValue: Add additional data via the open data model of Appointment Templates.
  • Import: The raw endpoint that handles all of the above.

Work items: tasks and jobs​

Every task needs to have a job. A job is the equivalent to an order or job in Business Central, while a task would represent service item lines, job tasks. A task is at the lowest level and is the plannable unit of work. The job holds information such as customer information and coordinates, while the task is about the work that needs to be carried out.

EndpointCreate/UpdateDelete
Job✅✅
Task✅✅
Task container✅✅
Task filter value✅✅
Task locked✅❌

The job model is a metadata type that captures information about the work that needs to be done. It contains data about the customer, the shipping and billing address, and more. Thus it does not store information about the actual work itself, which is reserved for the task entity.

A job by itself has not much use as they're not displayed in the open tasks grid until at least one task has been assigned to the job. In almost all cases, a job request will be succeeded by at least one task request.

Because there is so much information stored in the jobs model, a special builder or job factory class was designed. Using a fluent interface, you can construct a job without much fuss:

Job newServiceOrder = new JobBuilder()
    .WithJob("BC_CRONUS", "SERVICE", "SO001", "Update HVAC in Berlin office", "Maintain HVAC", "Simon Pecker")
    .WithCustomer(new Sdk.Import.Customer
    {
        Email = "[email protected]",
        Name = "HQ London",
        No = "HQ_LONDON",
        Phone = "123 423 091",
        Reference = "REF"
    })
    .WithBill(new Site
    {
        Email = "[email protected]",
        Name = "HQ London",
        No = "HQ_LONDON",
        Phone = "123 423 091",
        Address = new Address { FullAddress = "The Shard, Office 1234, London, United Kingdom" }
    })
    .WithContact(new Contact
    {
        Address = "Kommandantenstraße 18, 10969 Berlin, Germany",
        Name = "Contact 1",
        No = "CONTACT_001",
        Email = "[email protected]",
    })
    .Create();

The produced item is a plain old Job POCO, which can be passed onto the API.

Appointment​

An appointment is merely an assignment of a task to a resource on a given date and time. An appointment is the base entity, and an assignment entity represents the allocation of a resource to an appointment.

EndpointAppendDelete
Appointment✅✅
Appointment category✅❌
Appointment time marker✅❌
Appointment importance✅❌
Appointment locked✅❌
Appointment planning quantity✅❌
Appointment URL✅❌
Appointment Container✅✅
Assignment✅❌

Resources​

EndpointAppendDelete
Resource✅❌
Resource Calendar✅✅
Resource Capacity✅❌
Resource Filter Value✅✅
Resource GPS Tracking✅❌
Resource URL✅❌

Attributes & Requirements​

EndpointAppendDelete
Filter Group✅✅
Filter Value✅✅

Indicators​

An indicator is essentially a color representing a certain status. Categories display the background colors of appointments, while time markers render a underscore and pins display the colors of the markers on the map.

EndpointAppendDelete
Category✅✅
Time marker✅✅
Pin✅✅

Other endpoints​

EndpointAppendDelete
Action URI✅❌
Caption✅❌
Notification✅✅
Container✅✅
Last updated on by hbulens