Sending and receiving data

Sending data

All data is sent from NAV to Dime.Scheduler through the Dime.Scheduler REST Service. The Dime.Scheduler REST Service is a generic web service that uses a key-value pair schema which allows for unlimited flexibility in both the source and the format of the data and also allows for the business logic to reside within NAV.

ℹ️ We highly recommend to use the "empty" codeunits which are provided in a separate fob file to create custom solutions rather than modifying the standard add-on solutions objects. The standard add-on solutions objects will be modified with new functionality in future releases. By using the empty codeunits conflicting merges with future updates can be avoided. You can copy a standard add-on codeunit or a function thereof into an empty codeunit for your modifications. Don't forget to point to your codeunit or function, for example by updating the call to the function from one of the action buttons on a page.

Data types

The following types of data can be sent from NAV to Dime.Scheduler.

• Resources and the resources' filter values: remember that a resource is a general term and that you can send any data from NAV as a resource to Dime.Scheduler whether this represents a person, machine, (office) equipment, hotel or meeting room, car, etc.
• Jobs, tasks and the tasks' filter values: remember that jobs and tasks are general terms and that you can send any data from NAV as a job and its associated tasks to Dime.Scheduler whether these are from standard tables, custom tables or tables that are part of a vertical solution.
• Filter groups and filter values
• Categories: the category determines the color of an appointment.
• Time markers: the time marker is shown as a colored horizontal bar attached to the appointment.
• Pins: the pin determines the color of the markers shown in the map.
• Appointments: when a task is planned in Dime.Scheduler an appointment is created. From NAV you can create appointments directly into Dime.Scheduler, like when a holiday request from an employee is registered in the employee absence table of NAV, you can send that employee absence record as an appointment to Dime.Scheduler, thereby informing the planners immediately of the holiday. Given a proper security setup in Dime.Scheduler, planners will see that appointment but cannot modify nor delete it.
• Appointment updates: specific functions are provided to update an appointment's category or time marker. The category and time marker control the colors displayed on the planning board in Dime.Scheduler and are frequently used to visualize the status of an appointment. This could be used to indicate that a task has started, is in process, is completed or is overdue but also to show for example that the associated document or transaction in NAV has been invoiced.
• Task and appointment locks: Appointments can be locked or unlocked. A locked appointment is not editable in Dime.Scheduler. Individual appointments can be locked or unlocked and all appointments attached to the same task can be locked or unlocked.
• GPS tracking and asset location: when you receive or store GPS tracking or asset location data in NAV, you can send that data to Dime.Scheduler, thereby immediately updating the coordinates in Dime.Scheduler, which in turn allows the planners to better respond to planning requests.

Supported areas

To update data you have already sent to Dime.Scheduler, simply send the data from NAV again. Data is sent from NAV to Dime.Scheduler using codeunits or functions. These codeunits or functions can be triggered manually by the user using a button on the menu ribbon or form, executed during the process flow – e.g. when the status of a record changes – or scheduled.

The Dime.Scheduler Connector comes with a number of pre-built codeunits that support a number of standard tables or areas of NAV, including, but not limited to the following:

• Service orders
• Jobs
• Sales orders and quotes
• Production orders
• Employee absences

It is easy to extend or modify these codeunits, to develop own codeunits or integrate functions into other objects.

Developing a send function

All functions that are required to send data to Dime.Scheduler can be found in codeunits 2087625 "DS Web Service Management" and 2087644 "DS Dime.Scheduler Management". A send function calls the Dime.Scheduler REST Service, thereby passing the necessary parameters and when required, also sends document filter values.

The Dime.Scheduler REST Service expects 3 parameters:

• The function name to process the data
• An array with parameter names
• An array with the corresponding values

A send function constructs and sends those 3 parameters in 4 steps:

1. When it is required to transfer document filter values, the current record's RecRef is passed to the TransferDocFilterValues function of "DS Dime.Scheduler Management". The table to which the record belongs has to be setup in DS Doc. filter values. In case you forgot, document filter values are the filter values defined for a resource or task.

2. Initialization: call the InitParameters function of "DS Web Service Management", no parameters are required.

3. Populate the parameter arrays: call the AddParameter function of "DS Web Service Management" for each field. The AddParameter function requires 2 parameters:

   • ParameterName: the name of the field
   • ParameterValue: the value for the field

4. Call the Dime.Scheduler Web Service: call the CallDimeSchedulerWS function of "DS Web Service Management". The CallDimeSchedulerWS function requires 1 parameter:

   • StoredProcedureName: this is the name of the stored procedure or function that Dime.Scheduler will use to process the data.

Shown below is an example of codeunit 2087631 "DS Send Resource" which sends a NAV Resource to Dime.Scheduler that shows the 3 steps as well as the inclusion of the Document filter values (1).

For a complete and detailed overview of functions available in the Dime.Scheduler Web Service consult the developers manual. See also here for an overview of the codeunits and functions provided by the Dime.Scheduler Connector.

Calling a send function

To send data to Dime.Scheduler execute a codeunit's RUN-method or call the send function passing the record to be sent to Dime.Scheduler. A separate NAV object file (*.fob) is provided that contains a number of standard pages or forms onto which the send function is added.

As an example, on Page 5900 Service Order an ActionGroup is added in the Action Designer to send a Service Order to Dime.Scheduler. The RUN-method of codeunit 2087627 "DS Send Service Header" is executed passing the Service Header-record.

This is all what is required.

On Page 1002 Job Task Lines an ActionGroup is added in the Action Designer with the option to send a status update to Dime.Scheduler. In this example the category of the appointment in Dime.Scheduler – which sets the color of the appointment on the schedule – is used to visualize the status of the job task. By modifying the category of the appointment the color of the appointment is immediately updated in Dime.Scheduler, giving its users an instant visual insight of the overall status.

In this example the DS Source Type is used to retrieve the Appointment that belongs to the job task, see also the receiving data section to learn more about the DS Appointment table.

Such an implementation is also useful when displaying Dime.Scheduler on a separate (large) monitor as a master console or control room screen.

Receiving data

As you know, when planning a task in Dime.Scheduler an appointment is created. The appointment is immediately sent back to the NAV web service for Dime.Scheduler. For every change to an appointment in Dime.Scheduler, whether the new appointment is created or an existing appointment is modified or deleted, an entry is created in table 2087631 "DS Appointment". For every resource linked to the appointment (Dime.Scheduler supports multiple resources to be linked to a single appointment) an entry is created in table 2087632 "DS Appointment Resource". When there are custom fields on an appointment an entry containing the value for each field is created in table 2087642 "DS Appointment Field Value".

The "DS Appointment" record and its linked "DS Appointment Resource" and "DS Appointment Field Value" records are then processed by codeunit 2087635 "DS Handle Appointment". The source type that was sent with the task to which the appointment belongs and which is returned with the appointment is then used to determine which codeunit further processes the appointment's data into NAV.

This offers all the flexibility to handle planning or scheduling data in standard tables, custom tables or tables that are part of a vertical solution. This also guarantees that the appointment data is processed entirely through the business logic of NAV.

Field Name	Description
Entry No.	A unique, sequential number.
Source Type	The source type that is sent with the task to Dime.Scheduler is returned with the appointment. The source type defines how the appointment data is processed in NAV.
Source App	The source app that is sent with the task to Dime.Scheduler is returned with the appointment.
Job No.	Contains the identification of the job, the parent of task. For example this can be the service order, sales order, job or production order number.
Task No.	Contains the identification of the task. For example this can be the service item line or sales order line number or the job task number.
Appointment Id	The unique id of the appointment within Dime.Scheduler. This id allows you to update the appointment from NAV.
Subject	The subject of the appointment as shown in Dime.Scheduler. When you update the appointment from NAV you can: Return the subject as is. Send an empty subject. The subject is then generated by Dime.Scheduler as defined by the setup templates. Specify a value, thereby overwriting the subject in Dime.Scheduler. This allows you to send data from NAV as part of the subject shown in Dime.Scheduler and is yet another example of how to display status information in Dime.Scheduler based on the data and business logic of NAV.
Body	The body text of the appointment as shown in Dime.Scheduler. When you update the Appointment from NAV you can: Return the body as is. Send an empty body. The body is then generated by Dime.Scheduler as defined by the setup templates. Specify a value, thereby overwriting the body in Dime.Scheduler. This allows you to send data from NAV as part of the body shown in Dime.Scheduler.
Start	The start date and time of the appointment.
End	The end date and time of the appointment.
Time Marker	The current value of the time marker. You can use the appointment update functions to change the time marker in Dime.Scheduler based on the data and business logic of NAV.
Category	The current value of the category. You can use the appointment update functions to change the category in Dime.Scheduler based on the data and business logic of NAV.
Importance	The importance or priority of the appointment. Values are: 0 = None or Medium 1 = High 2 = Low
Duration (Sec.)	The duration of the appointment in seconds. Seconds is the base unit of measure for Dime.Scheduler.
Non Working Time (Sec.)	The amount of non-working time for an appointment.
Planning Quantity	The planned quantity expressed in the Unit of Measure. Calculated as: (Duration (Sec.) – Non Working Time (Sec.)) / Planning UoM Conversion
Planning Unit of Measure	The unit of measure code.
Planning UoM Conversion	The conversion from seconds to the unit of measure.
Use Fix Planning Quantity	Indicates whether the planning quantity is editable by the user in Dime.Scheduler (True) or calculated based on duration (Sec.) (False=default)
Round To Unit Of Measure	Indicates whether duration (sec.) is rounded to the unit of measure. Rounding is performed in Dime.Scheduler.
Last Modified Date	Date and time of the last modification
Last Modified User	User that made the last modification
Created Date	Date and time when then appointment was first created
Created User	User that created the appointment
Sent From Backoffice	Indicates whether the update of the appointment was made by the user (False) or by the back office (True)
Backoffice Id	Optional parameter that can be sent from the back office to link the appointment to a specific record. This information is simply returned by Dime.Scheduler.
Backoffice Parent Id	Optional parameter that can be sent from the back office to indicate the parent record of the record to which the appointment is linked. This information is simply returned by Dime.Scheduler.
Database Action	Indicates whether the appointment was created, modified or deleted in Dime.Scheduler. Values are: I = Insert U = Update D = Delete
Status	Status of the appointment record in NAV. Values are: New: the appointment record was received by NAV but not yet processed. Processed: the appointment record was successfully processed by NAV. Error: an error occurred during the processing of the appointment record. It is up to the user to take the necessary corrective actions after which the appointment record can be processed again.
Error Message	When an error occurs during the processing of the appointment record then this field will contain the last known error.
DateTime Received	The date and time when the appointment record was received by NAV.
Resource Report Filter	This field is used to retrieve the resource number that is passed by the action URI. Its only purpose is to extract the resource number from the URI and pass it to the defined codeunit.

The "Process" action on the menu ribbon or button on the form allows the user to process an appointment record manually.