Tasks
Basic Requirements
For the Task entity, attributes estimatedDuration, earliest, latest and status are mandatory for planning purposes2. In case material deliveries to mobile workers are involved, the requiredResource must be filled as well. The taskGroupId may be used to group different tasks that need to be planned as a bundle. Typically, the taskGroupId is used when more than one mobile resource or more then one day is required to perform the task3.
If a task is planned, both scheduled and scheduledFor must be provided. If the task is unplanned, these two attributes must not be provided.
Process Flows
For OMD Mobile, it is possible to control per task which functionality and mobile workflow is presented to the mobile worker. To understand how this works, it is important to understand the basic concepts of OMD Mobile4.
- A Task is an activity that a mobile worker will work on in OMD Mobile. For each task in the mobile worker’s agenda, the mobile worker can choose from two types of screens:
- Standard Screens: Standard screens are predefined screens in OMD Mobile. Available standard screens are:
- Notes: functionality to make notes. Notes can be used for internal or external e-mailing and reporting. These notes differ from text fields used in Mobile UI screens (see below)
- Barcode: functionality to start a logistic mutation using barcode scanning.
- Camera: functionality to capture an image for documentation purposes.
- Material: functionality to manually register logistic mutations.
- Call: functionality to make a call directly out of OMD Mobile.
- Map: functionality to visualize location using GPS and Google Maps.
- Signature: functionality to receive a signature of a customer or mobile worker.
- No Service: functionality to cancel a task.
- Mobile UIs: Mobile UIs can be created within OMD Configurator using a list of widget types, such as boolean, option, slider, integer, string and others.
- Task and Process Flow and Standard Screens: within a task, it is possible to define which combination of standard screens will be presented to the mobile worker. The definition of a combination has to be configured within OMD Configurator. The name of the combination as configured in the OMD Mobile Configurator has to be specified in the processFlow field of the task. For more details on process flow preferences, read chapter Process Flow Preferences of the Configuration Management document.
- Planned Items and Process Flow and Mobile UIs: A planned item, i.e. a process step within a task, can be defined as a task attachment (see Task Attachment definition below). Process steps are always linked to a Mobile UI screen, specified on the processFlow field of the task attachment.
- Standard Screens: Standard screens are predefined screens in OMD Mobile. Available standard screens are:
Example
As part of the Functional Design, OMD Customer A has defined two types of tasks:
- For Task Process Flow Type 1, the mobile worker will be able to use all standard screens. A customer signature is not required. Registration of hours and checklist X needs to be addressed.
- For Task Process Flow Type 2, the mobile worker will be able to use all standard screens. A customer signature is mandatory. Registration of hours and checklist Y need to be addressed.
How this is set up in OMD:
Step 1 - Define Task Process Flow: Within OMD Mobile Configurator, define the two types of Task Process Flows. Let us call them signature and noSignature. Basically, this is achieved by setting the process flow preference showSignatureIcon to true for process flow signature and to false for process flow noSignature. All other icons will be made visible, regardless of the task-specific process flow.
Step 2 - Define Mobile UIs: Within OMD Mobile Configurator, define three mobile UIs: hours, checklist X and checklist Y.
The Task definition on data level must then comply to the following rules:
Task Type 1: set the processFlow field on task level to noSignature. Add two itemsPlanned attachments to the task. The first itemsPlanned row contains the process flow value hours, whereas the second itemsPlanned attachment contains the checklist X value in the processFlow field.
Task Type 2: set the processFlow field on task level to signature. Add two itemsPlanned attachments to the task. The first itemsPlanned row contains the process flow value hours, whereas the second itemsPlanned attachment contains the checklist Y` value in theprocessFlow` field.
The Extra attribute
The extra attribute may contain additional information unavailable as a standard attribute in OMD. Typically, the extra attribute is used to inform mobile workers with specific work-related data. The data provided in the extra field can be rendered in OMD Mobile using specific stylesheets. Additionally, extra data can be used as default values in Mobile UIs or during reporting. Extra information must be provided as an XML document. Discuss the content of the extra attribute with your OMD consultant. Clarifying all required information upfront will avoid change requests once the screens or reports do not show all relevant information.
Note that during posting, XML documents in the extra field must be XML-escaped twice - once for the internal XML document in the extra attribute and once for the attribute content of the Task XML document.
Example
Suppose the extra information must contain the name of a service partner and the name of the service partner is Dupont & Dupond.
The escaped text for this name is Dupont & Dupond. Setting up the extra information in an extra XML document would look like the fragment below:
<Data partnerName=”Dupont & Dupond”/>
However, when sending this XML document inside of an XML attribute, the ampersand must be escaped once more:
<Task id=”123” extra=”&lt;Data partnerName=&quot;Dupont &amp;amp; Dupond&quot;/&gt;”/>
Note the character sequence &amp; is finally reverted into & by OMD, providing the correct content for further processing.
Task Splitting
Task splitting is a functionality within OMD Scheduler that can be used if (some of) the task supplied to OMD do not meet the standard requirement executed during a single working day or performed by an individual mobile resource. In that case, the imported task can be splitted (by calling a specific web service) in order to meet these requirements. Additional fields are available to further support this functionality, such as minimumResources and maximumResources. Task Splitting is regarded a workaround and can only be used in consultation with an OMD Consultant.
omd.domain.s4.Task
| Attribute | Description |
|---|---|
| id+ | A value that identifies the task uniquely throughout the configuration. |
| version | The version of the object. Versions change with every update of the database record. Task versions must always be 0 when posted to OMD. Read chapter Version Control for details. So called Replicated tasks are excluded from this, since they represent tasks outside of OMD’s control. |
| name* | The name of the customer for whom the task needs to be performed. |
| territory* | A task is assigned to a territory. It depends on the organization how many territories are used throughout the application. In case all tasks are performed in general territory, regardless of regional or functional grouping, the territory is the same for all resources. |
| department | An optional information, used in addition to the address fields. |
| street | The street of the location where the task needs to be performed. Street information can include housenumbers in local format (i.e. prefixed or postfixed). |
| postalCode* | The postal code of the location where the task needs to be performed. The postal code is used to geocode the task, i.e. to find the (x,y) coordinates for the location. |
| city | The city of the location where the task needs to be performed. |
| country | The country identifier for the task location. This information is used whenever organizations have resources/teams that cross country borders. Otherwise, the street, postal code and city name are sufficient to identify the location. Country codes are usually an abbreviation of the country name, i.e: BE for Belgium, NL for the Netherlands or DE for Germany. Please refer to the documentation of the Time Distance Module (TDM) for a complete list of supported country codes. |
| geocode | The geocode is a (x,y) coordinate for a location. Usually, the geocode is determined by the Scheduler and does not have be provided by the interface. Delivering the coordinate with the task may result in small perfomance gains due to less geocode processsing. |
| skill | This value indicates the skill that is required to perform this task. The Scheduler will only consider resources that have this skill. The value * means that every resource is capable of performing this task. If the implementation of the Scheduler requires to handle more than one skill for each task, this field can be used to express a constraint as a logical expression. Logical expressions can contain logical and (&&), logical or (||) and logical negation (!) predicates as well as parentheses for cascaded logical expressions. |
| estimatedDuration* | The estimated duration is defined in minutes. The value is used during the planning process to build a realistic planning for the resource performing the task. The estimatedDuration should not exceed 480 minutes, except when Task Splitting is used. |
| earliest* | The earliest possible date and time that the Scheduler may plan this task. |
| latest* | The latest possible date and time that the Scheduler may plan this task. |
| scheduled | The date and time that this task has been scheduled. If this field is filled, the scheduledFor field must be filled as well. |
| scheduledFor | The identifier of the resource that this task is assigned to. If the scheduled field is filled, this field must be filled as well. |
| requiredResource | This value indicates the id of the resource that must perform the task. The required resource is a hard restriction and results in an exception if the user tries to assign it to another resource. |
| preferredResource | This value indicates the name of the resource that should normally perform the task. Depending on the requirement of the organization, The Scheduler may disregard the preferred resource and assign the task to another resource if the costs are lower. See the Preferences section of the Technical Reference Guide for further details on how to define the preferred behaviour. Note that the mismatch of the assigned and preferred resource can result in additional costs. Therefore, assignment to another resource must be justified by a lower overall cost. |
| backupResource | If specified, the Scheduler regards this resource as a second option. If the assignment to the backup engineer is cheaper, the Scheduler will assign the task to the backup. |
| fixed | The date and time for which this task is appointed. Tasks have to be scheduled for exactly this datetime, regardless of better cost scenarios. |
| status* | The status of the task defines the state in which this task is currently in. The value depends on the workflow of the organization. Common status values are, for example, PL (Plannable), IP (In Planning) or CL (Closed). |
| actualDateTime | If a task is started or has already been performed, the ERP system may inform the Scheduler with the latest information about the task. By providing the actual start date and time, the Scheduler may adjust the planning of subsequent tasks for the resource who has performed the task accordingly. |
| actualDuration | If a task has already been performed, the ERP system may inform the Scheduler with the latest information about the task. By providing the actual duration, the Scheduler may adjust the planning of subsequent tasks for the resource who has performed the task accordingly. This information should only be provided in case the task is performed. Leave this field empty if the resource has started with the task, but is still busy. On the other hand, if the actual duration is filled, the actual start date and time must be filled as accordingly. |
| openingHoursMon | The opening hours for Mondays. The format of the value is fixed size string of 23 characters, containing 4 time indicators, for example, 07:30 12:00 13:00 17:00 to identify opening hours of 7:30 to 12:00 and 13:00 to 17:00. If only one opening exists, the value for the second opening can be set to 0s, i.e. 07:30 17:00 00:00 00:00. |
| openingHoursTue | The opening hours for Tuesdays. The format of the value is fixed size string of 23 characters, containing 4 time indicators, for example, 07:30 12:00 13:00 17:00 to identify opening hours of 7:30 to 12:00 and 13:00 to 17:00. If only one opening exists, the value for the second opening can be set to 0s, i.e. 07:30 17:00 00:00 00:00. |
| openingHoursWed | The opening hours for Wednesdays. The format of the value is fixed size string of 23 characters, containing 4 time indicators, for example, 07:30 12:00 13:00 17:00 to identify opening hours of 7:30 to 12:00 and 13:00 to 17:00. If only one opening exists, the value for the second opening can be set to 0s, i.e. 07:30 17:00 00:00 00:00. |
| openingHoursThu | The opening hours for Thursdays. The format of the value is fixed size string of 23 characters, containing 4 time indicators, for example, 07:30 12:00 13:00 17:00 to identify opening hours of 7:30 to 12:00 and 13:00 to 17:00. If only one opening exists, the value for the second opening can be set to 0s, i.e. 07:30 17:00 00:00 00:00. |
| openingHoursFri | The opening hours for Fridays. The format of the value is fixed size string of 23 characters, containing 4 time indicators, for example, 07:30 12:00 13:00 17:00 to identify opening hours of 7:30 to 12:00 and 13:00 to 17:00. If only one opening exists, the value for the second opening can be set to 0s, i.e. 07:30 17:00 00:00 00:00. |
| openingHoursSat | The opening hours for Saturdays. The format of the value is fixed size string of 23 characters, containing 4 time indicators, for example, 07:30 12:00 13:00 17:00 to identify opening hours of 7:30 to 12:00 and 13:00 to 17:00. If only one opening exists, the value for the second opening can be set to 0s, i.e. 07:30 17:00 00:00 00:00. |
| openingHoursSun | The opening hours for Sundays. The format of the value is fixed size string of 23 characters, containing 4 time indicators, for example, 07:30 12:00 13:00 17:00 to identify opening hours of 7:30 to 12:00 and 13:00 to 17:00. If only one opening exists, the value for the second opening can be set to 0s, i.e. 07:30 17:00 00:00 00:00. |
| remarks | Informational remarks that are associated with this task. |
| weight | The weight of the item(s) being delivered. |
| volume | The volume of the item(s) being delivered. |
| lastUpdate | The date and time this record has been updated. This information may help to increase performance during a plan refresh. Do not fill this field when uploading from an ERP system. Filling the field may produce update anomalies.The field will be filled with the latest timestamp while being stored. |
| contractType | The type of the contract may give the planner additional information about the response time. |
| requiresParts | This flag, consisting of a true or false value, indicates whether the task requires spare parts or not. |
| partsDelivered | This flag, consisting of a true or false value, indicates whether parts were delivered for the execution of the task or delivery is still pending. The field can be empty (NULL) to indicate that delivery of parts is not relevant for the task. |
| holidayCalendarId | The calendar that specifies the public holidays that are applicable to this task. |
| planAutomatically | if this field contains a "true" value, the task should be planned automatically by the Scheduler. If no value is specified, the task must be planned by the planner or by a batch run. |
| assignedDateTime | The date and time at which the resource starts to drive to the task location. |
| minimumResources | The task may have to be executed by a number of resources, depending on requirements. The minimum number of resources must be greater or equal to 1 and defaults to 1. |
| maximumResources | The task may have to be executed by a number of resources, depending on requirements. The maximum number of resources must be greater or equal to the minimum number of resources and defaults to 1. |
| taskGroupId | In some planning environments, it is necessary to bundle tasks into one sequential block. Rather than defining a series of task dependencies, these tasks can be identified by a unique task group id. The planning engine will attempt to plan these tasks into a single trip, if possible. |
| reschedule | This attribute is used to inform the planning engine about a task that is to be rescheduled. In that case, the schedule field is empty to allow for a new planning. However, if the task was planned within the dayoffset, the task should not be rescheduled at all. Instead, the task will be skipped. |
| rescheduleFor | This attribute is used to inform the planning engine about a task that is to be rescheduled. In that case, the scheduleFor field is empty to allow for a new planning. However, if the task was originally planned within the dayoffset, the task should not be rescheduled at all. Instead, the task will be skipped. |
| province | The state or province identifier of the task's address. States or provinces are not always used, but are frequently used in countries such as the United States. |
| positionInTrip | The position of the task within a trip. This field is only filled if the task is planned. It is used as a reference for external systems such as PDAs to identify the order in which the tasks appear in the trip. |
| acceptBeyondLatest | This flag indicates if planning algorithms should evaluate insertion points after the latest datetime. If true, algorithms will use the standard preference AcceptBeyondLatestDay to determine if planning after latest is acceptable. If false, any planning algorithm must accept the latest datetime. In this case, the standard preference is overruled. Default is true. |
| parkingGeocode | The (x,y) coordiante of the parking which should be used to deliver this task's location. Delivery services may have to park their vehicle nearby to deliver the attached locations by walking to the delivery address. The distance between the parking and the delivery address is added to the total of the travel distance. |
| taskType | This information is used to distinguish tasks. For example, a resource might have to deliver products or perform maintenance. Both activities can be distinguished by providing a different type. Note that this information is irrelevant to the planning engine. If the type of task puts a limitation on the resource candidates, use the skill attribute instead. |
| floating | A task is floating if it can be performed anywhere in the field. During calculations, the address of a floating task is determined by the address of the predecessor. |
| subGroup | Indicates the sub-division of a group, i.e. tasks belonging to subGroups need to be performed by distinct resources. This is frequently the case when two or more resources have to be on-site at the same location to perform work together. |
| roundEarliestLatest | In contrast to the general RoundEarliestLatest preference, the rounding to working hours can be applied to a single task by setting this value to true. If set to false, the earliest and latest values are only rounded if the general preference is set. |
| standby | If a task is marked as standby, it can only be planned for resources on days where the resource has a standby work pattern assigned. |
| resourcesRequired | The number of resources that are required for this task. In most cases, this number will be used to split the task into several tasks per resource, keeping a total equal to the original estimated duration. These tasks are then intended to be performed in parallel. |
| amount | Specifies the number of items that are to be processed. If not specified, a default value of 1 is used. If the task is related to several machines or items to be processed, this column may specify the exact amount of items. The number of items may be considered during reports. |
| imageURL | The location from where the icon for this task can be downloaded. |
| phone | The phone number of the customer or contact person. |
| A semi-colon separated list of e-mail addresses to which the Service Report or Proof of Delivery should be sent, after the task has been closed. | |
| processFlow | The identifier of the process flow that should be applied to this task. Depending on the process flow definition, mobile applications can include or exclude or adapt activities on the mobile device. If not specified, the standard process flow will be applied. |
| accountNumber | This value, if available, identifies the customer uniquely. |
| debtorNumber | This value, if available, identifies the debtor uniquely. |
| extra | Extra fields contain customer-specific information. Customer-specific information can be used during reports and other parts of the life-cycle of a task, but do not contain planning-releveant information. All values must be stored as attributes in an XML element called Data, for example: <Data poNumber="12345" serviceDoc="ABC1"/> |
| timeZoneOpeningHours | The time zone in which the opening hours are to be interpreted. The values needs to comply with ISO-8601. |
| locale | The country- and language-specific locale of the customer. This code is two-parted and complies with ISO-639 and ISO-3166 respectively (e.g. “de_DE” for German/Germany or “de_AT” for German/Austria) |
| formURL | The location of the ERP form for this task. |
| groupOffset | The offset defines the number of days between tasks in the same group. A value of 7 indicates that the next task must be planned exactly one week later. |
| groupOffsetMargin | When indicating a value greater than 0, the group offset can deviate from the exact offset by the specified number of days. |
2. Under certain circumstances the estimatedDuration can be calculated by OMD, if TaskAttachments of the Task provide Products or Product Categories with defined Estimates. See the OMD Configuration Guide for more information on estimate calculation. ↩
3. See the OMD Mobile Configuration Guide for more information about grouping criteria during task execution, besides the taskGroupId. ↩
4. For more details about OMD Mobile read the OMD Mobile Configuration Guide ↩