Import

The import endpoint

Any class that implements the IImportRequestable interface is eligible to be processed by the import service in Dime.Scheduler. All import requests are done through DimeSchedulerClient's Import property, which is an implementation of the IImportEndpoint interface.

Import types are simple POCOs, decorated by internal mapping and validation information. Behind the covers, these POCOs are translated to a type which the import API in Dime.Scheduler can interpret and execute. The import 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:

using Dime.Scheduler.Sdk.Import;

string uri = "http://mydimescheduler.com";
IAuthenticator authenticator = new FormsAuthenticator(uri, "admin", "admin");

DimeSchedulerClient client = new(uri, authenticator);

Category category = new("Category #1", "#6e62b5");
IImportEndpoint importEndpoint = await client.Import.Request();
await importEndpoint.ProcessAsync(category, TransactionType.Append);

This example adds or updates a filter group:

using Dime.Scheduler.Sdk.Import;

string uri = "http://mydimescheduler.com";
IAuthenticator authenticator = new FormsAuthenticator(uri, "admin", "admin");

DimeSchedulerClient client = new(uri, authenticator);

FilterGroup filterGroup = new FilterGroup { Name = "Group 1" };
IImportEndpoint importEndpoint = await client.Import.Request();
await importEndpoint.ProcessAsync(filterGroup, TransactionType.Append);

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

Validation

Validation is done through the capabilities exposed in the System.ComponentModel.DataAnnotations namespace. Wrapped in the interface IValidatableImportRequest<out T>, import objects are validated before the request is sent to Dime.Scheduler.

Take the FilterGroup class as an example:

public class FilterGroup : IImportRequestable, IValidatableImportRequest<FilterGroup>
{
    [Required]
    public string Name { get; set; }

    public int ColumnNo { get; set; }
}

When invoking the following request, an exception will be thrown:

FilterGroup model = new FilterGroup { ColumnNo = 1 };
((IImportRequestable) model).ToImportRequest(TransactionType.Append); // Will throw exception

The name wasn't populated and wouldn't be acccepted by the the import service anyway. As a result, there are two identical validation rounds: once in the SDK and once in Dime.Scheduler's import service.

Models

For an up to date list of the types and their properties, check out the source code. All import types live in the Dime.Scheduler.Sdk.Import namespace.

Work items

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.

Endpoint	Create/Update	Delete	Type
Job	✅	✅	Job
Task	✅	✅	Task
Task container	✅	✅	TaskContainer
Task filter value	✅	✅	TaskFilterValue
Task locked	✅	❌	TaskLocked

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 import request will be succeeded by at least one task import 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 = "hq@customer.com",
        Name = "HQ London",
        No = "HQ_LONDON",
        Phone = "123 423 091",
        Reference = "REF"
    })
    .WithBill(new Site
    {
        Email = "hq@customer.com",
        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 = "contact1@customer.com",
    })
    .Create();

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

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.

Endpoint	Append	Delete	Type
Appointment	✅	✅	Appointment
Appointment category	✅	❌	AppointmentCategory
Appointment time marker	✅	❌	AppointmentTimeMarker
Appointment importance	✅	❌	AppointmentImportance
Appointment locked	✅	❌	AppointmentLocked
Appointment planning quantity	✅	❌	AppointmentPlanningQuantity
Appointment URL	✅	❌	AppointmentUri
Appointment Container	✅	✅	AppointmentContainer
Assignment	✅	❌	Assignment

Resources

Endpoint	Append	Delete	Type
Resource	✅	❌	Resource
Resource Calendar	✅	✅	ResourceCalendar
Resource Capacity	✅	❌	ResourceCapacity
Resource Filter Value	✅	✅	ResourceFilterValue
Resource GPS Tracking	✅	❌	ResourceGpsTracking
Resource URL	✅	❌	ResourceUri

Attributes & Requirements

Endpoint	Append	Delete	Type
Filter Group	✅	✅	FilterGroup
Filter Value	✅	✅	FilterValue

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.

Endpoint	Append	Delete	Type
Category	✅	✅	Category
Time marker	✅	✅	TimeMarker
Pin	✅	✅	Pin

Other endpoints

Endpoint	Append	Delete	Type
Action URI	✅	❌	ActionUri
Caption	✅	❌	Caption
Notification	✅	✅	Notification
Container	✅	✅	Container

Using the import models

Let's say you would like to insert a new resource into the system. As you know by now, this is easy. Simply create an instance of the Resource class and pass it on the import endpoint:

using Dime.Scheduler.Sdk.Import;

string uri = "http://mydimescheduler.com";
IAuthenticator authenticator = new FormsAuthenticator(uri, "admin", "admin");

DimeSchedulerClient client = new(uri, authenticator);

Resource resource = new Resource { ... };
IImportEndpoint importEndpoint = await client.Import.Request();
await importEndpoint.ProcessAsync(resource, TransactionType.Append);