Sending and receiving data

Sending data

NAV sends all of its data to Dime.Scheduler through the Dime.Scheduler REST Service. This is a generic web service built on a key-value pair schema, which gives you full flexibility over both the source and the format of the data and keeps the business logic inside NAV.

ℹ️ We strongly recommend using the "empty" codeunits provided in a separate fob file to build custom solutions, rather than modifying the standard add-on objects. Those standard objects will gain new functionality in future releases, so working in the empty codeunits avoids merge conflicts when you update. Copy a standard add-on codeunit, or one of its functions, into an empty codeunit and make your changes there. Remember to point to your codeunit or function afterwards, for example by updating the call from one of the action buttons on a page.

Data types

You can send the following types of data 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. You can also create appointments directly from NAV. For example, when an employee registers a holiday request in the NAV employee absence table, you can send that absence record as an appointment to Dime.Scheduler and inform the planners of the holiday right away. With the right security setup in Dime.Scheduler, planners see that appointment but cannot modify or delete it.
• Appointment updates: dedicated functions let you update an appointment's category or time marker. The category and time marker control the colors shown on the planning board in Dime.Scheduler and are often used to visualize an appointment's status: that a task has started, is in process, is completed or is overdue, or, for example, that the related NAV document or transaction has been invoiced.
• Task and appointment locks: appointments can be locked or unlocked. A locked appointment cannot be edited in Dime.Scheduler. You can lock or unlock individual appointments, or every appointment attached to the same task.
• GPS tracking and asset location: when you receive or store GPS tracking or asset location data in NAV, you can send it to Dime.Scheduler to update the coordinates immediately, which helps planners respond better to planning requests.

Supported areas

To update data you have already sent to Dime.Scheduler, just send it from NAV again. Codeunits or functions handle the sending. A user can trigger them manually with a button on the menu ribbon or form, they can run during the process flow (for example when a record's status changes), or they can be scheduled.

The Dime.Scheduler Connector ships with pre-built codeunits that support several standard NAV tables and areas, including but not limited to:

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

You can extend or modify these codeunits, write your own, or integrate the functions into other objects.

Developing a send function

Every function you need to send data to Dime.Scheduler lives in codeunits 2087625 "DS Web Service Management" and 2087644 "DS Dime.Scheduler Management". A send function calls the Dime.Scheduler REST Service, passes the necessary parameters and, when required, sends document filter values as well.

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 builds and sends those 3 parameters in 4 steps:

1. To transfer document filter values, pass the current record's RecRef to the TransferDocFilterValues function of "DS Dime.Scheduler Management". The table the record belongs to must be set up in DS Doc. filter values. Document filter values are the filter values defined for a resource or task.

2. Initialize: 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: the name of the stored procedure or function that Dime.Scheduler uses to process the data.

The example below shows codeunit 2087631 "DS Send Resource", which sends a NAV Resource to Dime.Scheduler. It illustrates the 3 steps along with the inclusion of the document filter values (1).

For a complete, detailed overview of the functions in the Dime.Scheduler web service, see the developers manual. For an overview of the codeunits and functions provided by the Dime.Scheduler Connector, see the connector functions reference.

Calling a send function

To send data to Dime.Scheduler, run a codeunit's RUN-method or call the send function, passing the record you want to send. A separate NAV object file (*.fob) provides several standard pages and forms with the send function already added.

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

That is all you need.

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. Here the appointment's category (which sets the color of the appointment on the schedule) visualizes the status of the job task. Changing the category updates the appointment's color in Dime.Scheduler immediately, giving users an instant visual read on the overall status.

This example uses the DS Source Type to retrieve the appointment that belongs to the job task. See the receiving data section to learn more about the DS Appointment table.

This kind of setup is also handy when you display Dime.Scheduler on a separate (large) monitor as a master console or control room screen.

Receiving data

When you plan a task in Dime.Scheduler an appointment is created, and that appointment is sent straight back to the NAV web service for Dime.Scheduler. Every change to an appointment in Dime.Scheduler, whether it is created, modified or deleted, adds an entry to table 2087631 "DS Appointment". For every resource linked to the appointment (Dime.Scheduler supports linking multiple resources to a single appointment) an entry is added to table 2087632 "DS Appointment Resource". When an appointment has custom fields, an entry with the value for each field is added to table 2087642 "DS Appointment Field Value".

Codeunit 2087635 "DS Handle Appointment" then processes the "DS Appointment" record together with its linked "DS Appointment Resource" and "DS Appointment Field Value" records. The source type that was sent with the task, and returned with the appointment, determines which codeunit processes the appointment's data further into NAV.

This gives you the flexibility to handle planning and scheduling data in standard tables, custom tables or tables that belong to a vertical solution. It 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 the button on the form, lets the user process an appointment record manually.