1Configure Oracle Field Service

Your Company’s Configuration

You can configure Oracle Field Service to your specific business requirements, such as the type of work performed, the kinds of skills available for assignment, the way in which working calendars are organized, and so on. You can configure the settings for all these requirements on the Configuration page.

Most configuration settings are available on the Configuration page. However, depending on the way you have implemented the application for your company, some of the settings might be placed in individual menu items or grouped under different menu items. Your user type configuration determines the options displayed on the menus.

The configuration elements are grouped logically on the Configuration page:
  • General (the settings related to the general principles of the company operation):

    • About

    • Business Rules

    • Link Templates

    • Work Schedules

    • Work Zones

    • Work skills

  • Resources, Activities, Inventories (the settings related to the resources the company employs, the activities it performs and the inventory used in the course of their performance):

    • Properties

    • Capacity Categories

    • Time Slots

    • Resource Types

    • Activity Types

    • Inventory Types

  • Displays (the settings related to the general appearance of the application, page layouts, languages and translations):

    • Glossary

    • Display

    • Themes

    • Filters

    • Forms & Plugins

  • Users, Security, Integrations (the settings related to user management and system access):

    • Organizations

    • Login Policies

    • User Types

    • Applications

    • Oracle Knowledge

    • Integration Cloud Service

  • Subsystems (the settings related to Oracle Field Service modules):

    • Statistics

    • Outbound Integration

    • Collaboration

    • Message Scenarios

Items are added only to the groups listed earlier. Each item, when clicked, leads to the corresponding configuration page.

Configuration Page Access and Visibility Settings

You can allow or deny access to the Configuration page for each user type. This means, all users of that type either have the Configuration item in their menu or not. The visibilities that set the user access to this page are hidden, read-write, and read-only.

You can configure the items and their visibilities on the Configuration page in a dedicated context layout, Configuration. Similar to other context layouts, you can configure the Configuration page for each user type. This means that all users of the selected type see the same items on the page with the same level of visibility. The Configuration context layout can include only the company configuration items. Therefore, the Add property dialog box contains only the list of items related to company configuration. The reverse is also true—the company configuration items are not included in the action list of any other context layout.

How Plug-Ins are Configured

This topic describes the high-level steps to configure and use a plug-in in Oracle Field Service.

  1. Determine whether you want to host the plug-in in Oracle Field Service. If yes, prepare your plug-in for upload.

  2. Configure the plug-in.

    1. Upload the hosted plug-in.

    2. Add the available properties.

  3. Add the plug-in to the required page.

Configure a Plug-In

To use a plug-in in Oracle Field Service, you must configure it first.

  1. Click Configuration > Forms & Plugins.

    The Forms & Plugins page appears and displays the existing forms and plug-ins.
  2. Click Add Plugin.

    The Add Plugin page appears.
  3. Complete these fields:

    Field Name Description
    General Information section
    Name (English) A mandatory field defining the plug-in name in the English language. The action or plug-in appears under this name in the actual context.
    Name (other languages) Plug-in name translations to other languages, if used.
    Label A mandatory field defining a unique action or plug-in label.
    Entity Entity (activity, inventory, required inventory, resource, service request, user) to which the action or plug-in is to be related. For example, if you select Inventory, the action will appear only in the contexts related to inventory. Leave the field blank for the action to be available in all contexts of all the entities.
    Visibility rules similar to The base action from which the plug-in is to be derived, if needed. When a base action is selected, the resulting plug-in functions per the same rules as the base action. The base action affects only the visibility of buttons and not the functioning of the plug-in. It appears only in the contexts in which the base action appears and is shown or hidden according to the same visibility conditions. For example, if start_activity is selected as the base action for a plug-in, the plug-in is only be shown in the context of a pending activity when there is no started activity in the same route, similar to the Start action. The list of available base actions is filtered according to the Entity that is selected.
    Type The type of plug-in you want to use. Here are the options:
    • Native application: This means, the plug-in opens another application on the same device.

    • HTML5 application: This means, the plug-in uses an external application to extend the functionality. An HTML5 application plug-in can be used in one of these Mobility contexts - Activity List, Edit., View Activity, Inventory Grid or Add/Details Inventory. This restriction applies only for plug-ins that use the Plugin API. If this option isn’t selected, the HTML5 plugin is just a URL of an external resource that is opened in a new window or in an iframe.

    Fields for the HTML 5 Application Option
    Use Plug-in API Determines whether you want the plug-in to communicate with Oracle Field Service using the Plug-in API. If you clear this check box, the URL is just opened in a new tab/window/iframe. To interact with Oracle Field Service you must pass some data (such as activity id, resource name) to the plug-in using the placeholders in the "POST Data" and "URL" fields.
    URL The path to a URL (for external plug-ins). This URL executes the HTML5 application and it executes the plug-in in the entire browser window. The URL must start with the protocol (https). This field is hidden, if Hosted plugin is selected. The URL must point to the main file of the plug-in, if the “Use Plug-in API” option is selected. If “Use Plug-in API” is cleared, the URL must point to an external resource, which is opened either in a new window or inside Oracle Field Service in an iframe (if the “Tab or iframe layout” option is selected).
    POST Data The data that you want to be sent to the external plug-in. This field is hidden, if Use plugin API is selected.
    Disable plug-in in offline Determines whether you want to disable the plug-in when Oracle Field Service is offline. Clear this check box for the plug-in to work in offline mode. This field is hidden, if Hosted plugin is selected.
    Main menu items Determines whether the plug-in can be set as a Main Menu item through the Main menu context layout. This field is hidden, if Use plugin API is selected.
    Tab or iframe layout Determines whether the plug-in uses the iframe layout. If the field is cleared, the plug-in’s URL is opened in a new browser tab or window. This field is hidden, if Use plugin API is selected.
    Show scrollbars Determines whether the window in which the plug-in runs has scroll bars. This setting is applicable to the Legacy Manage application. This field is hidden, if Use plugin API is selected.
    Width in pixels/ Height in pixels The width and height of the plug-in window in pixels. This setting is applicable to the Legacy Manage application. This field is hidden, if Use plugin API is selected.
    These fields are displayed when you select the Use Plug-in API check box.
    Hosted plugin Determines whether you want to use a hosted plug-in. The fields that are displayed when you select this check box are displayed in the Host a Plug-in topic.
    URL The path to a URL (for external plug-ins). This URL executes the HTML5 application and it executes the plug-in in the entire browser window. The URL must start with the protocol (https). The URL must point to the main file of the plug-in, if the “Use Plug-in API” option is selected. If “Use Plug-in API” is cleared, the URL must point to an external resource, which is opened either in a new window or inside Oracle Field Service in an iframe (if the “Tab or iframe layout” option is selected).
    Disable plug-in in offline Determines whether you want to disable the plug-in when Oracle Field Service is offline. Clear this check box for the plug-in to work in offline mode.
    Authentication The type of authentication used by the external server hosting the plug-in source to verify access to the plug-in. This field is hidden when Native application is selected as the plug-in type. These choices are available:
    • Basic HTTP: The Basic Access Authentication method working over HTTP or HTTPS. The Basic HTTP authentication method requires a valid login and password. When the entered login and password are verified by the server, the server returns the plug-in content.

    • HMAC: Hash-based message authentication code verifying that the data is received from an authorized source. HMAC authentication method requires a secret key configured for each plug-in. This field is hidden, if Hosted plugin is selected.
      Note: The best practice is to use HMAC authentication instead of basic HTTP authentication. This is because, Google Chrome doesn't support the use of Basic HTTP authentication in sub-resources starting from release 59.
    Login/Password The user name and password to log in to the plug-in. These fields are displayed only when Basic HTTP is selected for Authentication.
    Secret key Displayed when HMAC authentication is selected. All parameters of the plug-in URL with replaced placeholders will be encrypted on the basis of the SHA-256 hash of the Secret Key value using the HMAC algorithm. The resulting string will be appended to the URL as the HMAC parameter.
    Secure parameters The section where secure information such as user name and password used to access external sites is entered. This section is available only when Use Plugin API is selected. The data entered here is encrypted and stored. Use the plus icon to add a new key-value pair. You can add a maximum of 20 key-value textbox pairs, after which the icon is hidden. The maximum size of the parameters allowed is 5 KB. This size includes the data structure overhead and doesn't correspond to the length of keys and values of strings. Changes to the secure data are sent to Oracle Field Service during the next synchronization. The data is sent to the plug-in when the next message is sent.
    Fields for the Native Application Option
    Native application name The name of the application to be launched by the plug-in.
    Browser user agents mask The browser in which the application is to be launched. The Native application link will be available in GUI, if the browser user agent matches the specified mask. For example, Safari, Android, iPad, iPhone.
    URL template The template for building the external application URL from properties. The URL template contains parameters key and placeholders for parameters value. Properties are interpolated with placeholders, surrounded with braces "{" and "}". For example: http://www.example.com/android? type=LOCATION'&'action=View'&'alt={acoord_y}'&'long=| {acoord_x}'&'address={caddress|url}'&'city={ccity|url}'&'state={cstate}'&'zip={czip}
    This screenshot shows the Add plugin page:
    This screenshot shows the Add plugin page, with the Available Properties section filled up.
  4. To add the details for another native application, click Add.

  5. To reorder the applications, click the stack icon and move the application up or down.

  6. To add the properties that are available to the plug-in through the plug-in API, click the pencil icon in the Available properties section.

    The Select properties page appears.
  7. Select the check boxes for all the properties that you want to be passed to the plug-in or updated by the plug-in. Click OK.

    The properties are saved. Unlike earlier, now you don’t have to define the visibility for the properties explicitly. You can add these properties to the list of Available properties as read-only. This means, these properties can't be updated through the Plug-in API:
    • activity_capacity_categories

    • auto_routed_to_date
    • auto_routed_to_provider_id
    • aworkzone
    • date
    • time_delivered

    You cannot add these properties to the list of Available properties:

    • activity_alerts
    • access_hours
    • activity_compliance
    • atravelarea
    • travel_estimation_method
    • service_window_end
    • service_window_start
    • eta_end_time
    • pid (it's still available for the Resource entity)
  8. Click Save on the Add plugin page.

How Plug-Ins are Hosted

If your plug-in consists only of HTML, CSS, and JavaScript files and doesn't contain server-side files, then you can upload it in Oracle Field Service. No additional hosting is required. The plug-in framework handles the communication between the hosted plug-in and Oracle Field Service. You can host a maximum of 25 plug-ins per instance.

The steps to host a plug-in are:
  • Complete the prerequisites to upload the plug-in.

  • Upload the plug-in.

After hosting a plug-in, you can:
  • Use it on a page

  • Move between instances

  • Modify

  • Rollback to a previous version

  • Delete

Note: A hosted plug-in works only with Oracle Field Service Mobility Cloud Service.

Prerequisites to Upload a Plug-In

The plug-in must be in a specific format to be uploaded. If not, you cannot upload it, you must host it elsewhere.

The plug-in files must meet these requirements:
  • You must upload a ZIP archive of the plug-in files.

  • You can upload only the files of following types:
    • .html

    • .css

    • .js

    • .jpg

    • .jpeg

    • .png

    • .gif

    • .svg

    • appcache

  • You can organize files in sub-directories, but you must have the "index.html" file in the root folder.

  • Each file can be a maximum of 1 MB and the total size of the compressed archive must be less than 500 KB.

  • You can have a maximum of 10 files or directories in the archive.

Note: The plug-in files uploaded in Oracle Field Service are available by unique URLs on the Internet. The URLs are generated automatically and contain a long string. There is no authentication to access these files, so anyone who has the direct link to the file can download the file. Therefore, don't store any sensitive information such as passwords or login names in the plug-in archive. If you don't want your code to be available without authentication, we recommend that you don't use the hosted plug-in functionality. Be aware that the communication between the plug-in and Oracle Field Service starts only when a user successfully logs in to Oracle Field Service.

Working Offline

You can create the plug-in to work offline using two possible approaches, or a combination of them.

The approaches are:
  • Using Service Worker API (See https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API): This is the preferred way to implement the offline functionality for the plugin. It is supported by most browsers, except Internet Explorer 11.
  • Using Application Cache API (deprecated) (See https://developer.mozilla.org/en-US/docs/Web/HTML/Using_the_application_cache): This is deprecated and will be removed in the future versions of modern browsers, but it's supported by Internet Explorer 11. The WHATWG (Web Hypertext Application Technology Working Group) notifies that Application Cache API feature is being removed from the web platform. Using any of the offline web application features at this time is highly discouraged. Use service workers instead.
  • Combination approach: Use the Service Worker API for modern browsers and Application Cache API as a fallback mechanism for Internet Explorer 11. The basic principles of this solution are:
    1. Create the mainfest.appcache file and link it with the index.html by adding the "manifest" attribute to main html tag:
      <html manifest="manifest.appcache">
      The manifest.appcache must contain the list of cached files in the "CACHE" section.
      Tip: Do not add "index.html" to the CACHE section to enable possible future updates of the plug-in's resources.
    2. Create the Service Worker javascript file (for example, service-worker.js). This file must implement the network behavior of your plug-in using ServiceWorker API. It may load "manifest.appcache" file on the "install" event, parse the Application Cache file and add all the files from the "CACHE" section to browser's cache using the CacheStorage interface. After that you can implement any network behavior strategies to handle the "fetch" event: "network first then cache", "cache first then network", or "network only".
    3. Register your Service Worker file at the JS part of your plug-in, before sending the "ready" post message, for example:
      if (navigator.serviceWorker) {
          navigator.serviceWorker.register('service-worker.js').then(function (registration) {
              this.startApplication();
          }.bind(this), function (error) {
              console.error('Service Worker registration failed: ', error);
              startApplication();
          }.bind(this));
      } else {
          startApplication();
      }

In this code example, the `startApplication()` function sends the "ready" post message. It's important to postpone sending the "ready" message until the "install" event is handled properly and all files from the CACHE section of manifest.appcache are loaded to the browser's cache.

Upload a Plug-In

You must upload the plug-in archive to use it as a hosted plug-in.

  1. Click Configuration > Forms & Plugins.

  2. Locate the plug-in for which you want to upload the archive. Click the stack icon and then click Modify.

    The Modify plugin page appears.
  3. In the Plugin settings section, ensure that the Hosted plugin check box is selected.

  4. Click Browse and select the ZIP archive that is ready for upload.

    The archive is uploaded only if these conditions are met:
    • The archive is a ZIP archive and has the extension .zip.

    • The size of the archive is less than 500 KB.

    • The archive includes only directories and files of these types:
      • .html files

      • .css files

      • .js files

      • .appcache files

      • .jpg, .jpeg, .png, .gif, .svg files

      • Directories

    • Files are less than 1 MB.

    • The "index.html" file is located in the root of the archive.

    • The archive includes a maximum of 10 entries, including empty directories.

    If any of these conditions is not met, an error message is displayed and the archive is not uploaded.
  5. Click Save.

    The plug-in details are saved and the Version history section is populated with:
    • The user name of the user that uploaded the files.

    • The date on which the archive is uploaded.

    • A link to download the archive.

    To be able to use the plug-in, you must add it to a button or a link. See the Add the Plug-in to a Page topic.

Modify, Download, or Delete an Archive

After uploading a plug-in archive, you might want to modify it, download it, or delete it.

  1. To modify a hosted plug-in, you upload a newer version. To upload a newer version of the archive, click Browse on the Modify plugin page and upload it again.

    You can have only two versions of the plug-in at any time. Whenever you upload a newer version of a plug-in:
    • The current version becomes a historical one.

    • The newly uploaded version becomes the current one.

    • The newly uploaded version is displayed in the first row of the Version history table.

    • The previous version is moved to the second row of the Version history table.

  2. To download a plug-in, click Download in the Version history section. Save it to the desired location.

  3. To rollback to a previous version, download the version that you want to rollback to. Click Browse and upload it again.

  4. To delete a plug-in, first unassign it from all the buttons it is added to. Then, click Delete on the Forms & Plugins page.

    The plug-in is deleted with all its historical versions.
  5. To move all the uploaded plug-ins between instances, export from the required instance using the Export function on the Forms & Plugins page. Import the exported files using the Import function in the target instance.

  6. To move a single plug-in between instances, download it from the required instance. Upload it in the target instance. You can use the Export option here as well.

Add the Plug-In to a Page

You add a plug-in to a context layout page, so that Field Resources can open it. You can configure the parameters for a button to send the parameters to the plug-in, or to open a specific page, or another plug-in.

  1. 1. Click Configuration > User Types.

  2. Select the type of user for which you want to add the plug-in.

  3. Click Screen configuration.

  4. Find and click the page to which you want to add the plug-in.

    The Visual Form Editor page appears. Plug-ins are available not only on the Visual Form Editor, but on old context layout structures such as Parts Details as well. On such pages, add an action and select a plug-in from the list.
  5. Drag-and-drop the Button element to the section from where you want to invoke the plug-in.

    Note: You cannot add buttons to context layout structures that are responsible for changing the state of an activity, simultaneously with submitting data. Some of the context layout structures where you cannot add buttons are Add activity, Not done activity, Install inventory, End activity. Further, you cannot remove or change the visibility of the two predefined buttons on these pages: Dismiss and Submit. This is to preserve the data integrity within transitions between states.
  6. Click the button.

  7. In the Standard action screen field, click the pencil icon.

  8. Select Plug-ins.

  9. In the Screens list, select the name of the plug-in that you want to open and click OK.

    The label of the plug-in is displayed in the Plug-in field. By default all plug-ins have a visibility of Read-only.
  10. In the Visibility section, add the conditions based on which the plug-in is visible.

  11. In the Translations section, add a name for the plug-in.

    This name is displayed on the page from which the plug-in will be invoked. This screenshot shows the Visual Form Editor page where a plug-in is added to the Button element:
    This figure shows the Visual Form Editor page, where a plug-in is added to the Button element.
  12. To configure the parameters:

    1. Click Add new in the Parameters section.

    2. Enter a name for the parameter in the Name field.

      For example, enter defaultScreen to define a page as the default page in the plug-in. The maximum length of the name that you can enter is 248 characters.
    3. Enter a value for the parameter.

      For example, enter part_order to display the Part order page as the default page in the plug-in. The maximum length of the value that you can enter is 4000 characters.
    4. Click Save.

    5. Repeat the procedure for all the parameters that you want to configure.

      The total combined length of all parameter names and values must not exceed 5000 characters. These parameters are not encrypted when sent to the plug-in.
  13. Click Save on the Visual Form Editor page.

    The plug-in is added to the selected page.

The Navigate Action

The Navigate action is a pre-configured link that opens a native navigation app on mobile devices. The Navigate link appears only when the user is online, offline, and when activities have resolved coordinates.

These links are pre-configured:
  • Android devices (browser user agent mask = *Android*) open a navigation application by geo: protocol for Android browsers.

  • iOS devices (browser user agent mask = *(?:iPad|iPod|iPhone)*) open Apple Maps.

  • All other devices (Browser user agent mask = *) open maps.google.com.

Modify the Navigate Action

You can modify the Navigate action, but note that changing this configuration could impact the users in the field. We recommend that you test the application properly before changing.

  1. Click Configuration > Forms & Plugins.

  2. Locate Navigate and click Modify in the stack menu.

    The Modify plugin dialog box appears.
  3. Enter the Native application name, Browser user agents mask and URL.

  4. Click Save.

    The new Navigate action is saved.

Activity Types

An activity is any time-consuming task such as, installation, trouble call, lunch, or team meeting that a resource does. Each activity type includes a set of features, which are yes/no flags and define the way the activity type is processed. Examples for features include whether activities of a specific type can be moved, created in a bucket, rescheduled, and so on. The Activity Types visibility controls the access to the Activity Types window. You must set the visibility for each user type that you want to manage Activity Types. If you don't configure an action for a user type or if you don't define the visibility, users of the user type cannot see the Activity Types. If you select ReadOnly, Activity Types is available in a read-only mode. If you select Read/Write, users can manage Activity Types.

Here is the detailed description of the features that may influence the processing of activity from the back office applications through Oracle Field Service.

Table Features that influence activity processing

Feature If enabled, the activities of the type...
Allow to create from Incoming Interface … can be created from external systems, including Oracle Field Service ETAWorkforce
Allow move between resources … can be moved between resources
Allow creation in bucket ... can be created in bucket through routing plans and profiles
Allow reschedule … can be moved to another day
Support of not-ordered activities … can be not-ordered – such that can be started by the resource before/after any other activity within the route
Allow non-scheduled ... can be activities without a date
Support of time slots … can use time slots (time-period within which they are to be started can be defined)
Calculate activity duration using statistics … are estimated using statistics that are gathered at the resource level and company level

Add an Activity Type

An activity type defines the properties based on which users can create activities. The properties could be whether the activity is created for customers, internal activities, or team work, whether travel has to be calculated for the activity, whether the activity can be rescheduled, and so on. You cannot modify some features after you start creating activities for some activity types. Whether you change the features for existing activity types on the user interface or through REST APIs, the application validates the features and displays warnings, as appropriate.

  1. Click Configuration > Activity Types > Add activity type.

  2. Complete these fields:

    Field Action
    Activity type info section
    Label Enter a unique identifier for the activity type.
    Name Enter a user-friendly name that appears in the interface. Enter the name in English and in all the languages that are active in the application.
    Active Specify whether the activity type is active. Users cannot select inactive activity types while creating activities.
    Group Select the activity type group this activity type belongs to, for example, Customer, Internal, Teamwork, or Task.
    Default duration Enter the time taken to complete the activity. This is the default value and it will be used when no statistics are available for the activity.
    Color Scheme Section
    Copy from The color palette to be copied from an existing activity type. The color scheme of the selected activity type is duplicated.
    Pending through Cancelled Define colors for each of activity statuses and for warning with standard RGB color codes and palettes. The colors that you select here are used on all the application pages. For example, let's say you select Green for the Started status. Whether you view the Time View, List View, or Manage, activities with the Started status are displayed in Green. The colors Pending = FFDE00, Completed = 79B6EB, Warning = FFAAAA, Suspended = 99FFFF, Not done = 60CECE, Not ordered = FFCC99, Started = 5DBE3F, and Canceled = 80FF80 are not available in the Supervisor Time View (Manage).
    Available Time Slots Section
    Available Time Slots Select the times slots for this activity type. You must have set up time slots in Configuration > Time Slots for them to be available on this page. Select the check box to activate the time slot.
    Features Section- The features are yes/no flags, which define individual characteristics of the type processing. If the check box is selected then the feature is enabled.
    Allow mass activities Select the check box to define that the activities of this type can be performed by multiple resources simultaneously. For example, team meeting, or training. If you select this option at the time of creating the Activity Type and save the Activity type, you cannot clear it later. However, if you have cleared it at the time of creating the Activity Type, you can select it later. But, you see a warning message.
    • This option cannot be enabled if Teamwork is selected.

    • This option cannot be enabled if Allow move between resources is selected.

    • This option cannot be enabled if Support of not-scheduled activities is selected.

    • This option cannot be enabled if Allow reschedule is selected.

    Teamwork Select the check box to define that the activities of this type are allowed for teamwork. Teamwork is an activity that is performed by minimum two resources: a team leader and an assistant. You can select this option only while creating the Activity Type. After you select this option and save the Activity type, you cannot clear it. Similarly, if you clear it at the time of creating the Activity Type, you cannot select it later. When the Teamwork activity feature is enabled, these activity type features are disabled:
    • Enable segmenting and extended duration

    • Allow move between resources

    • Allow creation in buckets

    • Allow reschedule

    • Allow non-scheduled

    • Enable 'day before' trigger

    • Enable 'reminder' and 'change' triggers

    • Support of work zones

    • Support of work skills

    • Support of inventory

    • Support of preferred resources

    • Allow mass activities

    Enable segmenting and extended duration Select the check box to define that the activities of this type are intended to be used for field work that must be split into segments, which can be scheduled and assigned to technicians. You can select this option only while creating the Activity Type. When you select this option, a new section, Enable segmenting and extended duration, appears in the Add activity type window where you can set the duration for segments. After you select this option and save the Activity type, you cannot clear it. Similarly, if you clear it at the time of creating the Activity Type, you cannot select it later. These fields are displayed in the Enable segmenting and extended duration section:
    • Minimum segment duration for a single day: Defines the minimum length (in minutes) of each segment the activity is to be split.

    • Maximum segment duration for a single day: Defines the maximum total duration (in minutes) of the activity segments for any day.

    When you select the Enable segmenting and extended duration feature, these activity type features are disabled:
    • Teamwork

    • Allow mass activities

    • Allow repeating activities

    • Enable 'day before' trigger

    • Enable 'reminder' and 'change' triggers

    • Enable 'not started' trigger

    • Enable 'SW warning' trigger

    Allow move between resources Select the check box to define that the activities of this type can be moved from one resource to another. You cannot select this option if you have selected Teamwork.
    Allow creation in buckets Select the check box to define that the activities of this type can be created in a bucket. If you select this option at the time of creating the Activity Type and save the Activity type, you cannot clear it later. However, if you have cleared it at the time of creating the Activity Type, you can select it later. But, you see a warning message.
    • You cannot select this option if you have selected Teamwork.

    • You can select this option only if you have selected Allow move between resources.

    Allow reschedule Select the check box to define that the activities of this type can be rescheduled to another date.
    Support of not-ordered activities Select the check box to define that the activities of this type can be not-ordered activities. If you select this option at the time of creating the Activity Type and save the Activity type, you cannot clear it later. However, if you have cleared it at the time of creating the Activity Type, you can select it later. But, you see a warning message.

    Not-ordered activities are the ones for which the order of execution is not defined. Such activities don't have an estimated time of arrival. The resource, dispatcher or routing may define the order (for example, command change order in mobile interface or edit activity command in web interface).

    Allow non-scheduled activities Select the check box to define that this activity type can have non-scheduled activities. You cannot select this option if you have selected Teamwork. If you select this option at the time of creating the Activity Type and save the Activity type, you cannot clear it later. However, if you have cleared it at the time of creating the Activity Type, you can select it later. But, you see a warning message.

    Non-scheduled activities are the ones that don't have a specific day of completion assigned to them.

    Support of work zones Select the check box to define that the resource work zone must be calculated for this type of activities. This option cannot be enabled if Teamwork is selected. If this option is selected and a work zone cannot be calculated, a warning is displayed when such an activity is moved; routing will not assign such activities. If using work zones, Business rules must be configured to allow support of work zones (Configuration > Business Rules > GUI features > Enable work zones support).
    Support of work skills Select the check box to define that the work skills are calculated and assigned to the activities of this type, based on any conditions met. Subsequently, only resources with matching work skills are considered for assignment of the activity. If you don't select this check box, work skills are not considered and the activity can be assigned to any available resource.
    • You cannot select this option if you have selected Teamwork.

    • This option does not depend on the Allow move between resources feature (as work skills are used not only to move activities but to calculate capacity).

    If you choose to use work skills, you must configure Business Rules to allow support of work skills (Configuration > Business Rules > GUI features > Enable work skills support).
    Support of time slots Select the check box to define that the activities of this type require time slots. This refers to pre-configured time slots within which the activity can be performed. After you select this option and save the Activity type, if you try to clear the option, you see the message, ‘Time Slot values will not be preserved after the change of this feature.’
    Support of inventory Select the check box to define that inventory can be used for activities of this type. For example, lunch breaks and team meetings do not have inventory. You cannot select this option if you have selected Teamwork. If you select this option at the time of creating the Activity Type and save the Activity type, you cannot clear it later. However, if you have cleared it at the time of creating the Activity Type, you can select it later. But, you see a warning message.
    Support of links Select the check box to define that the activities of this type can be linked with predecessor/successor activity relationships. If you select this option at the time of creating the Activity Type and save the Activity type, you cannot clear it later. However, if you have cleared it at the time of creating the Activity Type, you can select it later. But, you see a warning message.
    Support of preferred resources Select the check box to define that the activities of this type can have preferred resources (Preferred Resource tab). You cannot select this option if you have selected Teamwork. If you select this option at the time of creating the Activity Type and save the Activity type, you cannot clear it later. However, if you have cleared it at the time of creating the Activity Type, you can select it later. But, you see a warning message.
    Allow repeating activities Select the check box to define that the activities of this type can be recurrent. If you select this option at the time of creating the Activity Type and save the Activity type, you cannot clear it later. However, if you have cleared it at the time of creating the Activity Type, you can select it later. But, you see a warning message.
    • You cannot select this option if you have selected Allow move between resources.

    • You cannot select this option if you have selected Support of not-scheduled activities.

    Calculate travel Select the check box to define that the travel time to an activity must be calculated. If you have selected Calculate travel for an activity and it has neither the travel key (that is, zip code) nor coordinates, a company default value is used as a value of travel to and from the activity.
    • If the feature is selected, the algorithm implemented for activities is used for all activities of the type.

    • If the feature is not selected, the travel time to activities of the type is always calculated as zero (0) (as if location of activities of the type is the same as location of previous activity) and travel to the next stop also starts from this previous location.

    Calculate activity duration using statistics Select the check box to define that the activities are estimated using the statistics that are gathered at the resource level and company level.
    Allow to search Select the check box to define that the Oracle Field Service Search Engine indexes activities of this type.
    Allow to create from Incoming interface Select the check box to define that the activities of this type can be created from Inbound Interface. Activities may originate from either Oracle Field Service or external systems.
    Enable ‘day before’ trigger Select the check box to define that the day before trigger is invoked for activities of this type. You cannot select this option if you have selected either Teamwork or Enable segmenting and extended duration. You can select or clear this option at the time of creating the Activity Type, or later.
    Enable ‘reminder’ and ‘change’ triggers Select the check box to define that the 'reminder' and ‘change’ triggers are invoked for activities of this type. You cannot select this option if you have selected either Teamwork or Enable segmenting and extended duration. You can select or clear this option at the time of creating the Activity Type, or later.
    Enable ‘not started’ trigger Select the check box to define that the 'not started' trigger is invoked for activities of this type. You cannot select this option if you have selected either Teamwork or Enable segmenting and extended duration. You can select or clear this option at the time of creating the Activity Type, or later.
    Enable ‘SW warning’ trigger Select the check box to define that the 'SW warning' trigger (Service Window warning) is invoked for activities of this type. You cannot select this option if you have selected either Teamwork or Enable segmenting and extended duration. You can select or clear this option at the time of creating the Activity Type, or later.
    Calculate delivery window Select the check box to define that a delivery window can be calculated for activities of this type.
    SLA and Service window use customer time zone (required for routing) Select the check box to define that SLA/Service Window can be adjusted for the activities of this type. You must select this feature if you have selected Support of time slots.
    Support of required inventory Select the check box to define that the required inventory is supported for activities of this type.
    Disable resource tracking for this activity type Select the check box to define that the resource's geolocation is not tracked, if the activity has the status ‘Started’. The message, ‘Your location is not tracked for this activity.’ appears on the Landing page. Location tracking resumes after the activity status changes (that is, the status changes to ‘Completed/End’, ‘Suspend’, or ‘Not Done’) and, the route is still active. This functionality is supported in the Oracle Field Service Core Application (browser) and installed applications (Android and iOS) and requires Oracle Field Service Smart Location, Oracle Field Service Professional Cloud Service or Oracle Field Service Enterprise Cloud Service. This message is not displayed if you have not selected Enable GPS Telemetry under the Configuration > User Types > Permissions section.
  3. Click Add.

Find Activity Types

An activity type defines the specific parameters of the activity, such as which time slot the activity takes place. You may want to find activity types to view, edit, or clone them.

  1. Click Configuration.

  2. In the Resources, Activities, and Inventories section, click Activity types.

    The Activity types page appears and displays these columns:

    Column Description
    ID System-generated number assigned to records in the database – not used by anyone except the Support team.
    Activity Type Name The user-friendly name the end user sees in the drop-down list of choices on the Activity page.
    Status Indicates if the activity type is being used.
    • Green check mark = Active and in use

    • Red X = Inactive and not used

    Activity Type Label A unique identifier for the activity type.
    Actions Links to the actions you can take on this activity.
  3. Click View.

  4. Type the activity type that you want to find in the Find field.

  5. Click Apply.

    The results appear in the work area with the search criteria in bold.

Activate, Deactivate, or Delete Activity Types

If you don't want to use an activity type any more, you can either deactivate it, or delete it. Similarly, if you have an existing deactivated activity type, you can activate it and start using it.

  1. Select the check box next to an activity type.

    Options appear at the top of the page.
  2. Click the appropriate button, based on the action you want to perform.

    Note: Deactivate does not delete the activity type; it just makes it inactive.

How Activity Duration Is Calculated

You can define the activity duration or the application can calculate it using statistics that it obtains from learned durations.

Note: You can specify durations for specific activities and technicians through APIs. For more information, see the REST API for Oracle Field Service guide.
The manually-defined and statistical methods work as follows:
  • Manually-defined: If you have not selected the Calculate activity duration using statistics check box on the Add activity type or Modify activity type dialog box, the duration specified at the time of creating the activity is used. If you have not specified the duration in the activity, the default duration for that activity type is used.

  • Statistical: If you have selected the Calculate activity duration using statistics check box on the Add activity type or Modify activity type dialog box, the duration of the activity is calculated based on statistical methods. If the history is not enough to calculate using statistics, the duration entered manually (if entered) at the time of creating the activity is used. If neither history nor a manually entered value is present, then the default duration for that activity type is used. The default duration is specified at the time of creating the activity type.

Calculation of activity duration using statistics

Activity duration estimations are calculated by the application based on the historical data of completed activities. The application analyses new data, compares it against previous estimations, and corrects the previous estimations, based on the new data, to obtain updated estimations for future usage. For this, the application uses two main statistics: company profile and personal profile. The application learns how each technician performs tasks and updates these statistics daily.
  • Company profile: The activity duration is calculated at the company level based on the Activity duration stats fields configured on the Statistics page. All activities belonging to the same field value are grouped together for calculating the duration. The key is typically something that identifies similar activities as a single entity including fields such as Activity Type. When a technician performs tasks and reports the time against them, the company level estimate is derived for each task type based on the stats field values. The application gives more importance to more recent data for computation, rather than historic data. This increases the estimation accuracy and allows the application to respond to changes in trends in a timely manner. The default duration specified in the Add activity type dialog box is used as the starting point for estimating the duration. The application:
    • Refers to the previous experiences of similar tasks.

    • Calculates the estimate based on the summary of experiences.

    • Learns from new experiences.

    • Updates and remembers the updated experiences for future use.

    Every day the estimate is modified by a small amount, based on the durations reported on the previous day for similar activities. The correction applied is controlled to ensure that there isn’t too much deviation from the previous estimation and the estimated durations don't keep fluctuating on a daily basis; but is significant enough to respond to any trend change within a few days.
    The formula to calculate the new estimate is:
    New estimate = Previous estimate +/- Correction
    where correction is based on previous estimates and the differences between the estimated and reported durations.
  • Personal profile: The company level estimate and the estimated time for the activity for the technician are computed in the form of a ratio. This ratio is calculated based on the company level estimate for the activity. The final estimate at the technician level is the product of the personal profile ratio and the company level estimate. Each technician may have different ratios for different types of activities, based on their performance. Similar to the correction applied to the Company level estimates, the Personal profile ratio is also updated by a small controlled amount every day, based on the durations reported by the particular technician on the previous day for similar activities. When a technician performs an activity for the first time, the default ratio is used. Ratios are also calculated for each bucket for each kind of activity, based on the durations reported by the resources under the bucket. This ratio is used to estimate the duration when the activity is assigned to a bucket and not yet assigned to a technician. This is also the duration that is used for Capacity and Quota calculations, if the activity is assigned at the bucket level.

Overrides

You can override activity durations for each activity duration key value at either the Company level or the Technician level, using REST APIs. The Override is stored in the application, in addition to the learned statistical value for the currently active Activity key. For duration estimations, if an override is specified for the user, the overridden value is used instead of the statistically learned value. However, the statistically learned value continues to be updated based on the new reported durations as currently done.

Some more important points about activity durations:
  • If the personal profile is not available for an activity key value, the default ratio for the technician is used.

  • The default ratio has an initial value that is specified in the Initial Ratio for Activity Duration field. This value is updated each time the technician performs a relatively new activity.

  • You can specify which type of resources use personal profile, using the Personalize the estimation of activity duration field. If you do not select this option, such resource types do not use the personal profile and use only the company wide estimations.

  • You can specify whether a resource affects the company level estimates, using the Use durations reported to enhance company-wide estimations field. If it does, you can also specify the number of days to be skipped to avoid impacting the company estimates while the resource is new and still learning how to perform activities. The duration reported by only those resources that satisfy these two conditions is used to modify the company level estimates.

  • You can set upper and lower limits for activity durations at the resource or bucket level, as a percentage of the company wide estimations. You can use using the Lower/Upper limit for personal ratio for duration calculation fields for this. The estimated Activity duration values always remain within the set limits.

The fields that affect activity duration are:

Field Page Description

Minimum and maximum relevant duration time in minutes

Statistics These specify the acceptable values for reported durations to be considered for estimating Activity Durations. If technicians report durations outside of this range, the application does not consider that value when estimating durations.

Lower/Upper limit for personal ratio for duration calculation

Statistics These specify the range within which the duration estimation for technicians and buckets would lie as a percentage of the company level estimation. If the estimation at the technician or bucket level, as a percentage of the company level estimation, is lesser than the set lower limit, the estimation is set to (Lower limit * company level estimation). Similar modifications are done if the percentage is more than the set upper limit.

Default duration

Add activity type and Modify activity type This is the duration used for estimation, if no other estimation is available including override or historical data for that kind of Activity to estimate duration statistically. This value is also used as the estimated duration, if Calculate activity duration using statistics is cleared, or no duration is specified on Activity creation.

Calculate activity duration using statistics

Add activity type and Modify activity type This parameter specifies whether the duration of the activity must be estimated statistically using historical data. If cleared, the duration specified at the time of creating the activity, or the default duration is used.

Personalize the estimation of activity duration

Add resource type This parameter specifies whether the activity duration estimation must be learnt for each resource separately. If selected, the application estimates personal profile ratios for each resource for each kind of activity separately. If cleared, the application uses the company wide estimations.

Use durations reported to enhance company-wide estimations

Add resource type This parameter specifies whether the durations reported by the resource must be considered while calculating activity or travel estimations.

Don't consider reported data of the first x working days

Add resource type This parameter specifies the number of days only after which the durations reported by a new resource are considered for enhancing statistical estimations. Till such time the durations reported by a new resource are not considered for duration calculation purposes. This field is editable, only if the previous parameter is selected.

Initial ratio for Activity Duration

Resource Info This is the default ratio that is used for the resource, if there isn’t enough historical data for the resource for a particular type of activity. For such activities, the estimated duration of the technician is the value of the Initial ratio * company wide estimation (provided “Personalize the estimation of activity duration” is selected).

Working days left for reported data to start impacting duration estimations

Resource Info This parameter specifies the number of days left before the reported duration of the resource starts affecting the estimated duration. The initial value is based on the value set in Don't consider reported data of the first x working days.

Flowcharts

The following diagrams show how Oracle Field Service determines activity durations. The first flowchart is based on the assumption that the Personalize the estimation of activity duration check box is not selected for the resource type, and therefore the activity duration estimate is not adjusted by the resource’s personal profile or initial ratios.
This flowchart shows how activity duration is calculated when the Personalize the estimation of activity duration check box is not selected.
The second flowchart is based on the assumption that the Personalize the estimation of activity duration check box is selected for the resource type. This means, the activity duration estimate is adjusted by the resource’s personal profile or initial ratio.
This flowchart shows how activity duration is calculated when the Personalize the estimation of activity duration check box is selected.

Configuration examples

Example 1: Application uses the duration that is provided at the time of creating the activity
  • Activity Type dialog box:

    • Default duration = 30

    • Calculate activity duration using statistics = not selected

If the activity created has a duration of 50 minutes, that value (50) is used. If no value is provided at the time of creating the activity, 30 minutes is used.

Example 2: New resource in the application has no historic data. The administrator wants to provide 20% more time than the estimated duration at the company level.

  • Resource Type dialog box: Personalize the estimation of activity duration = selected

  • Resource Info page: Initial Ratio for Activity Duration = 120%

  • Activity Type dialog box: Calculate activity duration using statistics = selected

  • Assume company-wide estimation for the activity to be 45 minutes

Since the resource does not have previous records for this kind of activity the initial (default) ratio is used for calculations. The estimated duration for the resource is: 45 * 120% = 54 minutes

Example 3: Application uses technician’s learned duration with limits. Resource has performed activities of this type in the past and, hence, has a personal activity key ratio.

  • Statistics page:

    • Lower limit for personal ratio to calculate duration = 50%

    • Upper limit for personal ratio to calculate duration = 200%

  • Resource Type dialog box: Personalize the estimation of activity duration = selected

  • Activity Type dialog box: Calculate activity duration using statistics = selected

  • Assume personal profile to be 40% and company-wide estimation for the activity to be 50 minutes.

Since the personal activity key ratio is less than the lower limit of 50%, the application uses the lower limit value of 50% for calculations instead of 40%. The estimated duration for the resource is 50 * 50% = 25 minutes.

Example 4: Application uses company duration without using personal profile

  • Resource Type dialog box: Personalize the estimation of activity duration = not selected

  • Activity Type dialog box: Calculate activity duration using statistics = selected

  • Assume company-wide estimation for the activity to be 45 minutes

Since the personal profile is not configured, the estimated duration for the resource is same as the company wide estimation = 45 minutes.

Example 5: Application uses overridden value at technician level instead of learned statistics
  • Resource Type dialog box: Personalize the estimation of activity duration = not selected

  • Activity Type dialog box: Calculate activity duration using statistics = selected

  • Assume personal profile to be 80% and company-wide estimation for the activity to be 50 minutes

  • Assume that the duration for the resource for the Activity key has been overridden by a value of 30 minutes

The overridden value takes precedence over the learned duration at the resource level. The estimated duration is 30 minutes and not 80% of 50 = 40 minutes.
Example 6: Reported durations outside the acceptable range are not used as input for Activity duration estimation
  • Statistics page: Minimum relevant duration time in minutes = 5 mins

  • Statistics page: Maximum relevant duration time in minutes = 1440 mins

  • Assume that the estimated duration for the activity was 20 minutes and a resource starts and completes the activity in 4 minutes. That is, the resource reports a duration of 4 minutes for a completed activity.

Since the reported duration lies outside the acceptable range of 5 to 1440 minutes, the duration of 4 minutes is not considered to enhance the estimated duration of the activity key and the estimated duration remains unchanged at 20 minutes (assuming there weren’t any other reported activity that could have changed the estimated duration).

Activity Duration Statistics Fields

You can configure multiple activity duration statistics keys, so that you can compare the quality of keys. Data is collected for all the keys, and the quality ratings of the keys are displayed on the Statistics page.

With multiple activity duration statistics fields you can:
  • Configure up to five keys and choose any one of them to be 'Active' at any point of time.

  • View the quality of each key.

  • View all the configured keys in the 'Work Statistics' report and view the report for specific keys as well.

Only the 'Active' key is used for estimating activity duration. Although the application collects data for all the configured keys, the keys that are not 'Active' are not included in the calculation. The advantage of this feature is that before making a new key 'Active', you can compare the performance of the new key with the existing one. This happens without affecting the current calculations.

The quality of the key is displayed as stars next to each key. More number of stars indicates better quality of estimation. Based on the quality of keys, you may choose to 'Activate' any of the currently inactive keys. When you activate an inactive key, the currently active key becomes inactive. If another key has better quality than the currently active key, the 'Activate' button is displayed beside the key. For all other inactive keys, the Activate option is available within the options menu. You cannot delete an active key; you can only delete inactive keys. To delete a key, first make it inactive, and then delete it.

New or modified keys

Whether you add a new key or modify an existing one, the application considers both of these as new keys. When the application gets a new key, the Activity duration estimation algorithm is run on the next day (or the next time the recalculation process is run). This gives the estimated durations of all keys based on the new key. The application then calculates the quality of the new key based on the historical durations and the calculated estimated durations. Further, when an existing key is modified and the recalculation process is yet to run, the message, "Changes have not been applied yet" is displayed. The key that is currently in effect (previously active key) is also displayed until the new key takes effect.

Existing keys

The estimated durations for all key values and the quality of each key (Active and Inactive) is calculated every day. The Activity durations that are actually used in the application are calculated based only on the Active key. Hence, if you change the status of a key from Inactive to Active (or Active to Inactive), the quality of the keys is not affected. Similarly, since the estimated duration is also calculated for inactive keys, the learning that is applied since the key is created, is still in effect when an inactive key is activated. Similar to other keys, changes in an existing key or activation of a new key comes into effect only when the recalculation process runs the next time (typically by the next day). Similarly, the quality of a new or modified key is displayed only from the next day onward.

Calculating the quality of keys

The application calculates the quality of each key based on how accurate the estimation of Activity durations have been or would have been, if the key was used for calculations. These steps are used:
  • The estimated duration is calculated for each type of activity (Activity key value) using the key for which the quality has to be found.

  • Durations reported by technicians, for completed past activities are compared with the estimated duration for that activity using the said key.

  • If the difference between the estimated and reported duration is less, the estimation is considered to be good. If the difference between the estimated and reported duration increases, the quality is considered to deteriorate.

  • The final quality of the key is calculated based on the number of activities that showed good, satisfactory and bad estimations, for that key.

Consider this example:
  • Key 1 = Activity Type (2, case insensitive)
  • Key 2 = Plant Code (2, case insensitive), Problem Code (2, case insensitive)
This table shows the data to demonstrate how the quality of a key is calculated:

Activity ID Activity Duration Key based on Key 1 Activity Duration Key based on Key 2 Estimated Duration based on Key 1 Estimated Duration based on Key 2 Reported Duration Quality of Estimation based on Key 1 Quality of Estimation based on Key 2

1

AA PP11 50 90 52 Good Poor

2

BB PP22 75 70 68 Good Good

3

BB QQ22 75 95 100 Satisfactory Good

4

CC QQ22 100 95 125 Satisfactory Satisfactory

5

AA RR11 50 35 45 Good Satisfactory

6

DD PP11 150 90 135 Good Poor

7

BB RR22 75 45 30 Poor Satisfactory

8

DD PP11 150 90 140 Good Poor

9

AA RR22 50 30 20 Poor Satisfactory

10

CC QQ11 100 140 110 Good Satisfactory

The quality of a key is calculated based on these formula: Quality of Key = (0.06 * % of Good Estimations) + (0.04 * % of Satisfactory Estimations)

Based on this formula:
  • Quality of Key 1 = 4.4
  • Quality of Key 2 = 3.2

Work Statistics report: All the configured keys appear on the Work Statistics report. The user can select any key (Active or Inactive) and the report displays the updated values based on the selected key.

Activity duration stats fields: The formation of the keys (made up of fields) used for the grouping of work duration values to find the averages. You can define up to five activity keys and have one active key at any time. Data is collected for all the keys, and the keys are rated for their quality. Stars indicate the rating and more number of stars indicate better quality. For more information, see the Activity duration statistics fields topic.

Pre-Calculated Travel Statistics

Travel statistics are based on the actual durations reported by field resources. As such, new customers and existing customers expanding into new operating areas will not have actual durations in the application. The application uses pending and completed activities to derive estimated durations using point-to-point estimations. Using this method improves travel durations at the time of optimizing routes and moving activities.

Oracle Field Service performs this process once a day:
  • Get the list of activities and their locations.

  • Estimate the probability of travel in future between each pair of ’Activity travel stats fields' (Travel Keys). The travel probability is calculated for all Travel Key pairs, based on the relative distances between them.

  • Sort Travel Key pairs in descending order, based on distance.
    Note: Travel Keys that have existing learned travel are excluded from the estimation process.
  • Estimate the travel duration using point-to-point estimations for a maximum of 12,000 pairs based on the sorted list.

After performing the process, the application has additional travel duration data. The next time Routing runs, or a user moves an activity, the application uses the pre-calculated travel values. Calculating probability and sorting Travel Key combinations:
  • Activities that have valid coordinates with an accuracy value of either 8, 9, or 0 are considered. Travel coordinates with an accuracy value of ‘0’ are provided by customers.

  • Travel Keys that have at least one activity with valid coordinates are considered for estimation.

To find out the relative distances between pairs of keys, the application calculates the median coordinates for each key. This is done based on the median values of the latitudes and longitudes of all activities that belong to the travel key. The median values of latitude and longitude are calculated separately.

The application also finds the coordinates of the two closest activity locations to the calculated median for each key. The coordinates of these medoids are used when sending pairs of locations between keys.

Algorithm

The general rules of the algorithm are as follows:
  • Travel keys are sorted based on the number of activities corresponding to the key. Pending Activities carry higher weights than completed ones.
  • The algorithm starts from the most popular key in the list that does not have learned duration to at least one other key within 150 kms. After the request is started from that key, the algorithm moves to the next most popular key and repeats the process.
  • If there is no travel data from a key to itself, the application sends two pairs of coordinates within that key as a part of the request.
  • Between the keys, the application prioritizes the travel between nearest keys, based on the distances calculated between the medians.
  • The algorithm ensures that there is always at least two pairs of locations between any two keys. The final travel estimation is the average of the two travels.
  • Keys that are more than 150 kms apart are not considered as a part of the request.

    Example

    Consider a geographical location, where each cell represents a Travel Key. Keys in lighter shades denote keys that do not have travel estimations from that key to itself. The request starts from the most popular key that is not connected to at least one key within 150 kms. The request traverses 13 unique keys and comes back to the original key. Thus, each request contains 24 travels. The final request would be A-G-H-I-J-E-I-K-L-K-J-M-N-O-N-M-J-K-I-E-J-I-H-G-A:
    This image shows a request that has traversed 13 unique keys and returned to the original key.
    The request then moves on to the next most popular key, say V and repeats the same process. On the way if there is a key that is not connected to itself, the application includes two travels within the key. Whenever such a case is encountered, the key is counted twice when counting 13 unique keys. The next request would be V-Q-P-P-P-O-R-T-S-S-S-R-U-U-U-T-U-R-S-T-R-O-P-Q-V:
    This image shows the next request.

    This process continues till 1000 requests are sent on that day or no more non-connected neighbouring pairs are left to be sent. After the entire process completes for enough number of days, the learned travel estimations from every key to every other key within 150 kms of itself will be available.

Configure Business Rules

Business Rules help you configure the application to suit your requirements.

The Business Rules visibility profile permission controls the access to the Business Rules page. You must set this permission for each user type that manages Business Rules. If the action is not configured for a user type, or if no visibility is defined, the users don’t see the Business Rules page. If you select ReadOnly, Business Rules is placed into a view-only mode. If you select Read/Write for this setting, the user can manage Business Rules in Oracle Field Service.

  1. Click Configuration.

  2. In the General section, click Business Rules.

    The Business Rules page appears.
  3. Complete these fields:

    Field Description
    General
    Work Skills Support

    Work Zones support

    If a feature is disabled (unselected) the settings defined for it are retained in the application, but no restrictions are applied.
    Work skills and work zones are critical settings greatly affecting performance, particularly, activity assignment to resources. When they are enabled, they impose these constraints on the process of activities assignment and reassignment:
    • Routing takes into account work skills and work zones and assigns activities only to resources matching the work skill and work zone requirements of the activities.

    • All newly-created activities have work skills and work zones calculated for them and, therefore, will be correctly assigned afterwards

    • Self-assignment, Quota management, manual activities move or assignment are subjected to work skills and work zones check

    All these factors contribute to higher application performance and help improve the use of the workforce. Disabling work skills support and/or work zones support may result in Routing results below optimum and, therefore, must be used with care.

    Service Window Support If selected, by default the Service Window placeholder is selected when an activity or teamwork is created (must be defined).
    Points Support Select the box if you use points. When points are used, each shift and corresponding work schedule is assigned a certain number of points, which are a relative expression of the required work to be performed within such work schedule. Similarly, each activity may be also assigned a certain number of points. As the resource completes activities in their route, their points are added and compared to the total number required for the work schedule. Points may be used by Routing in activities assignment.
    Overnight Work The number of hours for overnight work since midnight. Used only if you have overnight work activities. Select the time zone used to define the work-day closure from the drop-down list. If the value is greater than 0, it is possible to create activities for the previous day’s route and perform other route modifications based on the time zone setting value.

    Working time ____ hours since midnight <…..>

    This setting affects the logic of data saving by the Daily Extract functionality. If the company does not support overnight shifts, the extraction period covers time since the previous extraction till the end of the previous day. If the company supports overnight shifts, the Daily Extract data for the previous day are available for extraction after the overnight expiration, i.e., at 00:00 AM + overnight. If the data is extracted before that time, the resulting files will contain data of 2 days before. It is recommended to schedule Daily Extraction several minutes after the overnight expiration to guarantee that only the relevant data is extracted.

    Full-time Equivalent Used in the Planning section of Calendars. The value is a company wide setting. The value converts the calendar to a Full-time Equivalent resource. For example: If the resource works from 08:00-16:00 (8 hours) and the Full-time Equivalent value = 8 this resource will be shown as 1 Full-time Equivalent.
    Expose mass and repeating activities for these number of days The number of days in advance in which the template activities are created in technicians’ routes automatically.

    The default value is '0', which means that such activities are not instantiated automatically, but are created only when a route is created. When you modify the value and save it, Oracle Field Service scans all the technician routes and instantiates the templates for the dates that match the configured period. If you increase the value, then the application includes more dates into consideration for automatic instantiations. If you decrease the value, then the application does not remove the existing instantiated activities, instead processes fewer dates from then on. When you add a new resource or change the templates and schedules, the application changes the activities accordingly.

    Note: Instantiating activities may require significant time, especially if you increase the value and there are many technicians in the application. It also generates a significant amount of transactions such as events (routeCreated, activityCreated) and outbound messages for the "Activity is created" launch conditions.
    Activity Priority Activity priority is used by Routing to assign urgent activities, immediate activities, and to prioritize activities for self-assignment on the map. You can use any custom property of activity with type string, enumeration, or integer, but not fields. The configuration consists of these parameters:
    • Property to define priority: Defines the activity property that will be used to identify urgent, immediate, and self assignment activities.

    • Urgent activities have these values of the property: Defines the specific values of the property, which make the activity urgent or immediate. Several values of the same property can be used as criteria. In this case the values must be separated by commas in the field. The order of property values defines the priority level. The value listed first will have the highest priority, with other values following in the descending order. For example, if you have a privileged customer, you may specify it as a specific value (such as "PC") in an activity property, so it qualifies the activity as urgent. For enumeration properties, you must specify the enumeration values.

    • Normal activities have these values of the property: Defines the specific values of the property, which make the activity normal. For example, in-house activity selected as "IN" in an activity property may qualify the activity as normal.

    When activities are routed using the immediate routing run option or the urgent routing option, the priority specified in the field that you select here are considered. For example, a company must always perform repairs as soon as possible to reduce service disruptions. In this case, the company may have a custom property which indicates that the activity is "Repair" to consider an activity as urgent. The preferred ETA for Urgent activities is the earliest possible time. SLA start time does not have any impact on Urgent activities, which means, SLA violation is expected behavior. Further, even if you select Immediate routing, SLA start time does not have an impact on the Urgent activities ETA.
    Enable the Visit functionality Define Bundling Keys for a Visit
    Visit Bundling Keys Define Bundling Keys for a Visit
    Maps and Geocoding
    Available Countries Geocoding is the process of finding associated geographic coordinates (latitude and longitude) from other geographic data, such as street addresses, or zip codes (postal codes). Geocoding data is required for Routing and is critical for Map/driving directions.

    Proper geocoding information is necessary for every country that this instance of the application is operating within. The Available Countries field allows adding additional countries for geocoding purposes.

    Select the + symbol to select an additional country form the drop-down list. Select the pencil icon to edit the country name for localization purposes.

    Default Country for Geocoding Determines from which country the Available Country list above is used as the default country for geocoding.
    Zip Code Format Defines the format of ZIP (postal) code and state code values, when applicable. Both fields are used in the activity coordinates resolution from its geographic address. The ZIP value is validated by the Inbound API, therefore, its format is important. When the ZIP value sent by the Inbound API does not correspond to the format set in the Business Rule, the API returns an error. However, when the Free Post code option is selected, the ZIP value is not validated and will always be accepted.
    State Format The State format field includes Free format and US. Select US for addresses in the USA having a strict 2-letter state code format. For all other countries with different civil entity systems, select Free.
    GPS Identify technician by – Determines how a unique technician is identified within the context of GPS plotting.
    These items are applicable with Oracle Field Service Smart Location Cloud Service:
    • Resource is considered idle if moved less than __ meters within _- minutes

    • Resource is considered to be at the activity location if the distance is less than __ meters -

    Map Parameters Defines the items related to the Map page:
    • Distance Measurement Units: Specifies whether distance is measured in miles or kilometers.

    • Ignore coordinates with accuracy less than: Sets the minimum sufficient accuracy level for geocoding. The minimum sufficient accuracy level is the coordinate’s accuracy which is considered acceptable for usage. The coordinates below the specified level will not be used as insufficiently accurate.

    • Baidu Maps and Geocoding parameters: Indicates the server key and browser key for Baidu maps, which are used to authenticate the user or organization using the service.
      Note: Driving directions for Oracle map and geocoding are only shown in these languages: (English (default), French, German, Italian, and Spanish). The default maps and geocoding provider is Oracle. Google or Baidu can be used, if it is part of your subscription. To use Google or Baidu maps, contact Oracle Sales. Further, you can have only one provider (Oracle, Google, or Baidu) configured in the application. Information about the geocoding provider is displayed on the Configuration > About page, Enabled Services section.
    Map Layers Lets you add two types of map layers: Work Zone layer (work zone shapes) and custom map layers (for example, places of interest such as gas stations or gas pipelines) on top of the map. You can add a Work Zone layer or a new map layer, modify or delete an existing layer, and change the permissions for an existing layer. When you click Add new, the Add Map Layer dialog box appears. You can either upload shape files through the interface or through an API, or you can provide the path to MapViewer from where the custom layer is obtained. You also see these sections:
    • Status: Indicates the status of the layer. If the shape file is uploaded successfully and is ready for use, the status displays a green check mark. If the shape file is not uploaded properly or has any errors, the status displays a red cross mark.

    • Map layers: Provides the name of the map layer and the date on which it was last updated. If the map layer is not available, this column provides the reason such as: Shape loading failed.

    • Permissions: User types to which the layer is assigned. If there are multiple user types, they are displayed as, ‘<user type> and <number> more’. For example, ‘Technician and 3 more’. This column is empty for the Work Zone layer.

      Note: The Permissions option is not available for a Work Zone layer.
    Properties of Work Zone layers:
    • Each Work Zone can have only one map layer, and if it does not exist, the message, No configured layers appears.

    • You can create only one Work Zone layer. After a Work Zone layer is created, the Create Work Zone layer option is grayed out on the Add map layer dialog box and the message "Only one layer for work zone shapes can be created" is displayed.

    • When you delete a Work Zone layer through the metadata API, only the layer is deleted. The shape files are not deleted from the database. However, when you delete a Work Zone layer from the Manage interface, by selecting the Delete associated shapes option, the layer and its associated shapes are deleted.

    Nearby Radius and Nearby SLA Defines the criteria of the nearby activities search on the Nearby page. It does not affect the Scheduling layer on the Map page. The Scheduling layer shows all activities in the visible part of the map.

    The Nearby Radius value sets the radius of the circular area in which nearby activities is to be searched. The Nearby SLA parameter sets the SLA expiration period which activities must have to match the search criteria. The default values are 50 kilometers as the radius and 60 days as the SLA. The minimum values are 1 km and 1 day, respectively. The maximum values are 1000 km and 1000 days, respectively. As the result, the functionality searches a circular area with the center in the resource location and the radius equal to the Nearby Radius value, selecting the activities with SLA expiring within the period defined as Nearby SLA. Any activities not conforming to these criteria will not be included in the search results.

    Company Boundaries The latitude and longitude coordinates of the company’s geographical work area. Activities can be performed only within these boundaries that are a set of squares. To identify a square, its top left and bottom right corners are defined. If no boundaries are defined the company can perform work anywhere. Additional boundaries can be added by clicking the + symbol.
    Retention period
    Activity, Inventory, Service Request and History information The retention period for the activities in the past, customer related inventory, service requests, and the associated activity history. It also includes the service requests, messages, logs such as activity history, quota history, configuration log, changes to resources and users. The default value is 90 days. You can set a value between 1 and 90 days. The background data purge process takes into account the updated value whenever the process runs the next time. If the difference between the changed numbers is huge (for example, you change from, 90 to 3 days), the purge process may take up to 24 hours.
    Caution: Do not set the value to 1 (one), if you have set the 'Overnight work' setting on Business Rules to a number greater than 0 (zero). If you do so, your data may be purged before the Daily Extract process runs.
    Collaboration History The retention period for Collaboration chat history. The default value is 90 days. You can set a value between 1 and 90 days. The background data purge process takes into account the updated value whenever the process runs the next time. If the difference between the changed numbers is huge (for example, you change from, 90 to 3 days), the purge process may take up to 24 hours.
    Resource Position History The retention period for the resource's GPS coordinates. Resources locations are extracted as part of the Daily Extract process. You can retrieve them through the 'Get last known positions of resources' and 'Get position history for resource for certain date' Core API requests. The default value is 90 days. You can set a value between 1 and 90 days. The background data purge process takes into account the updated value whenever the process runs the next time. If the difference between the changed numbers is huge (for example, you change from, 90 to 3 days), the purge process may take up to 24 hours.
    Note: The value for this field must be less than the value for 'Customer, resource and user information'. As part of the background data purge process for 'Customer, resource and user information', information about queues are also removed. Resource locations are gathered at the queue level, so they cannot be shown on the page when the queue is removed.
    Daily Extract files The retention period for files that are generated by the Daily Extract process and retrieved through the 'Download daily extract file' Core API method. The default value is 90 days. You can set a value between 1 and 90 days. Updated value is taken into account for when the Daily Extract files are generated the next time. The retention period for existing Daily Extract files is the period that was defined when files were created.
    Quota Management
    Quota Management These items are applicable with Oracle Field Service Capacity Cloud Service:
    • Measurement units for Quota and Available Capacity

      Defines the general settings affecting Quota Management functionality. Particularly, the user can choose the units of measurement to display Quota and Used values by setting the Quota and available capacity are defined in parameter. The available values are hours, man-days and minutes. Internally, all values are calculated in minutes anyway, and are converted to the selected unit when the corresponding value is displayed in the Quota View.

      When man-days is selected as the unit of measurement, the Number of hours per man day is field appears where the correlation between man-days and hours can be defined. Ultimately, this parameter is used to convert man-hours into minutes.

      When the Quota is defined as percentage of the capacity available by calendar, sometimes it requires adjustment. To adjust the value, the system estimates the capacity available by calendar, processes the already booked activities (to calculate the Other activities value), and, finally, recalculates the Quota in minutes using the defined percentage value.

    • Recalculation period

      You can set a predefined time interval for Quota and Capacity recalculation using the every [ ] minutesfield.

      Valid values: 1 to 1,440 minutes

      Default value: 10 minutes

      Also, you can recalculate quota and capacity for a predefined future period (defined as days or calendar weeks). For example, if you enter 10 minutes and set 3 calendar weeks for Quota and Capacity recalculation, then the recalculation occurs after every 10 minutes for 3 calendar weeks.

      The Calendar Week (duringdrop-down list) option is processed based on the value selected from the First Day of the Weekdrop-down list in the Display page.

      When you use the Calendar Week option, all remaining days of the current week (unless the start day is the week start day selected using the First Day of the Week drop-down list) plus all days of these weeks are considered.

      However, if the recalculation period is set to 7 days, the recalculation is performed for 7 days only. The maximum value for the Calendar Week option is set to 99 days or 15 calendar weeks.

      You can select the recalculation start day (current day, tomorrow, or day after tomorrow) from theThe Corresponding quota values are automatically adjusted starting from drop-down list.

      The Quota and Capacity is recalculated for the Available Capacity, Booking Status, and Quota pages.

      Note: When an activity is booked during the predefined recalculation period, then irrespective of the routing schedule and the specified recalculation period, the values in the Available Capacity, Booking Status, and Quota pages are recalculated immediately.
    Capacity Intervals See Define Time Intervals section in the Oracle Field Service Capacity Cloud Service Guide.
    Search Fields Define the Activity Search Fields and Define the Inventory Search Fields
    Note: Search uses the first 40 characters of the search string. Inventory search does not support enumeration type fields.

Configure Activity Map Markers

You can configure map markers to differentiate between the non-scheduled and not assigned activities that are displayed on the Scheduling layer on the Route map and on the Dispatch Console map.

  1. Click Configuration > Business Rules.

  2. In the General section, go to Non-scheduled Not assigned activity map markers.

    You can see that Urgent (red big circle) and Other (yellow small circle) are available by default.
  3. Click the pencil icon.

  4. On the Activity map markers dialog box, click the plus icon, and complete these fields:

    Field Description
    Activity Markers The predefined shape to indicate the activity.
    Filter The condition to display the activity. All the filters that are configured on the Configuration > Filters page that satisfy these conditions are displayed here:
    • The entity is Activity.

    • The List/Time/Map/Daily check box is selected.

    If you have selected a dynamic field such as Activity type or Work zone, a field appears below Filter to add the value. You can use the same marker with multiple filters.
    Filter value The value for the condition. For example, if you have selected Activity type for Filter, select Installation for the Work Type. You can use the same filters multiple times, with different conditions. For example, you can use the Days to SLA filter with conditions equal to 2 or 7.
  5. Click OK. Repeat steps 4 and 5 and add more markers.

    You can add a maximum of 10 markers.
  6. Use the stack icon to reorder the markers.

    The first marker in the list gets the highest priority, the second marker gets the second priority and so on. When multiple activities are displayed in a cluster on the map, the application determines the marker based on the priority assigned to it.
    Note: You cannot reorder Urgent and Other markers.
  7. Click the minus icon to delete a marker.

  8. Click OK on the Activity map markers dialog box.

  9. Click Save on the Business Rules page.

How Geocoding Works

Oracle Field Service attempts to geocode a location using the address data that is provided when the activity is created.

The application uses these fields when attempting to geocode the location:
  • Address (caddress)

  • City (ccity)

  • State (cstate)

  • Zip/Postal Code (czip)

  • Country (country_code)

Data provided in these fields are submitted to the geocoding service without any modification or manipulation. When the geocoding service resolves a location, it returns a response with an accuracy level. In understandable terms it is accurate up to the address, accurate up to the street, and accurate up to the city. The location is resolved based on the selection made in the Ignore coordinates with accuracy less than setting on the Business Rules page. For example:
  • If the value for Ignore coordinates with accuracy less than is Address, and the geocoding service returns Accurate up to the Intersection, the location is not resolved, because the lowest acceptable level based on the configuration is Address.

  • If the value for Ignore coordinates with accuracy less than is Intersection and the geocoding service returns Accurate up to the Address, the location is resolved, as it exceeds the lowest acceptable level based on the configuration of Intersection.

Ignore coordinates with accuracy less than includes these options in descending order:
  • Address: Indicates an accuracy level of the exact premise. Usually requires an exact match of the address (including house number, street name, street type/suffix/prefix), city, state, zip, and country.

  • Intersection: Indicates an accuracy level of a major intersection, usually of two major roads.

  • Street: Indicates an accuracy level of a street.

  • Route: Indicates a named route (such as US 101). This may not apply to all countries.

  • Zip: Indicates an accuracy level of the zip/postal code. May also require a city name and country match.

  • City: Indicates an accuracy level of the city. May also require the country name to be matched.

  • County: Indicates an accuracy level at the county level. This type may indicate a minor civil administrative level. Not all countries have this type of administrative levels.

  • State: Indicates an accuracy level at the state level. Within the United States, these administrative levels are states. Not all countries have this type of administrative levels.

  • Country: Indicates an accuracy level of the country. If you update an existing activity (with resolved coordinates) with a new country_code, the coordinates for the activity are reset to zero (acoord_x=0, acoord_y=0).

The better the data quality, the more likely the location is resolved. For example - if you submit “10 Henr St Chartley, MA 02712”, the accuracy level will most likely result in something less then an accuracy level of Address, because Henry is misspelled. Other items to watch out for are extra characters or spaces in the fields, missing or wrong address prefix or suffix, abbreviations that don't match postal guidelines, a new address that is not in any geocoding service, wrong data (wrong zip/post code or street name), and partial data. Any of these items can cause challenges with resolving an address.

Best practices

  • We strongly recommend that you send us the geo-coordinates when you create activities. This ensures that the coordinates are available for use in the application. Send the values using Coordinate X (acoord_x) and Coordinate Y (acoord_y). These values are also required for some features available in the Oracle Field Service Enterprise SKU when Google Maps is used (for example, real-time travel adjustments).

  • For the activities associated with the Activity Types that have the Calculate travel option selected, we encourage you add and populate address fields. This helps the application use the information to make the best possible decision.

  • We recommend setting the Ignore coordinates with accuracy less than to Zip. Any other settings may result in fewer locations being resolved or too many locations resolved with a low level of accuracy.

  • don't include additional address elements in the Address (caddress) field. The element includes but is not limited a business name, unit, flat, suite, floor number, and so on.

  • Avoid uncommon abbreviations, or abbreviations that are part of a defined standard used by the postal authority. It is possible that “Ave”, “Ave.” and “Avenue” can lead to different accuracy resolutions.

  • You may have to experiment to find the best way to send address data to Oracle Field Service.

Add a Map Layer

Map layers are layers that are added on top of a map. The layers may include those places of interest that are specific to your business. You can add layers through an external source, or internally through APIs. Use APIs to upload shape files for each layer that you want to create and configure the shape files on the Manage page. You can also add a layer for your work zone, which is visible to all users.

If you are adding a map layer internally, you must upload the shape file through the metadata API.
Note: Work Zone layers are not displayed on the Map view.
  1. Click Configuration.

  2. In the General section, click Business Rules.

  3. In the Maps and Geocoding section, click Add new.

    The Add Map Layer dialog box appears.
  4. Select whether you want to create a Work Zone layer or a map layer.

    You can add only one Work Zone layer; after you add it, the Create work zone layer option is grayed out.
  5. Enter the name of the layer in the preferred language.

    The languages displayed here are the languages that you have selected for Company language in the Display page. This option is not available for the Create work zone layer option. The application adds the name ‘Work Zone Layer’ automatically and translates into the required languages.
  6. Add a label for the custom layer in the Label field.

    If you have added a custom layer through the metadata API, the name is suggested as you type it. If you have not added any layer through API and you don't add an external source, you cannot save the layer. This option is not available for the Create work zone layer option. The application adds the name ‘wz_layer’ automatically and translates into the required languages.
  7. Select the status of the layer in the Status drop-down list.

    A layer with the Active status is available and a layer with the Inactive status is not available. This option is not available for the Create work zone layer option.
  8. Select the location from which you want to use the shape for the layer:

    • Upload shapefile later via API: Select this option to upload a shape file through API.

    • Upload shape now: Select this option to upload a shape file now. These fields are displayed:
      • URL to shape file: Enter the URL to the location where the shape file is available. Use only a secure protocol, that is, a HTTPS URL.

      • Username and Password: Enter the username and password to access the shape file location.

      • SRID: Enter the shape identifier that was generated in the application in which the shape was created.

    • Use external data source: Select this option to use an external data source to display custom layers. This functionality requires Oracle MapViewer where the layers are created and stored. These fields are displayed:
      • MapViewer URL: Path to MapViewer from where the layer data is obtained.

      • Data source: The source of the map layer data used by MapViewer.

      • Theme: Layer name in MapViewer.

      All the fields are mandatory. If a field is left empty, the window is rejected with the error message: {field_name} is empty.
    • Use already uploaded shape: Select this option to use a shape that is already uploaded. The list of available shapes is displayed and these details are displayed:
      • Layer label: The label of the layer.

      • Last updated: The date on which the shape file was last updated.

      • Source URL: The URL in which the shape file is uploaded.

  9. Click OK.

    By default, users of all user types have access to the new custom layer. If the status is Active, the application verifies if:
    • Data for this layer is present in the database.

    • Data is consistent and not corrupted.

    • There are no errors when displaying the layer on map.

    If these conditions are satisfied, the layer is saved and displayed on these map pages:
    • Team map: Accessed from Mobility > Map

    • Activity List map: Accessed from Mobility > Activity List > Map

    • Activity Details map: Accessed from Mobility > Activity Details > Map

Review this information before uploading shape files:

Requirements for the shape file:
  • The shape file must be in a zip archive.

  • The shape file must be in the root of the zip archive, not inside any folder of the zip archive.

  • If more than one shape file is present in the root of the zip archive, the first shape file of the default zip archive reading sequence is processed and saved. The rest of the shape files are ignored.

  • Column names in the shape file must contain only alphanumeric characters and underscore ('_').

  • Column names must begin with an alphabet.

Shape file restrictions:
  • When uploading a shape file using HTTPS, these restrictions apply: WebLogic's default certificate validator does not accept certificates with wildcards (including Google Drive certificate).

  • SRID value should be a valid SRID.

  • A maximum of 2 GB is available for extracted shape file data that is uploaded and hosted in Oracle Field Service.

  • If a shape file contains a column with the name "SHAPE_AREA" (case insensitive), it is renamed as “SHAPE_AREA_".

  • If a column name is same as an Oracle Database reserved word, then an underscore ("_") is prefixed to the column name. The full list of Oracle Database reserved words is available at: Oracle Database Reserved Words.

Recommendations:
  • It is recommended that you use shape files with compressed data size less then 50 MB. The shape file data is extracted and stored in the browser memory (when showing to end user), so the size of the file may heavily influence the browser performance, including the inability to show the map layer.

  • It is not recommended to use polylines for work zones.

Display a Work Zone Layer on a Map

You can display a Work Zone layer on the map, only if you have added it to the Business Rules page. Before you display a layer on the map, you must select the shape identifier on the Edit Map Layer dialog box. The shape identifier helps you identify the shape when you are working on a different page. For example, the shape identifier can be the internal serial number.

  1. To select the shape identifier:

    1. Click Configuration > Business Rules.

    2. Go to the Map layers section.

    3. Click Modify against the layer for which you want to add the shape identifier.

    4. In the Edit Map Layer dialog box, select a value in the Shape Identifier drop-down list.

  2. To display the Work Zone layer on the map:

    1. Click Configuration > Work Zones.

    2. Select or create the work zone for which you want add the shape identifier.

    3. Add the value of the shape identifier in the Work Zone Shapes field.

    4. Click Update or Add.

      The work zone shape corresponding to the selected shape identifier is displayed on the map.

Update Shape Properties

After you upload a shape, you can modify its properties such as visibility on the Map hint.

  1. Click Configuration.

  2. In the General section, click Business Rules.

  3. In the Map layers section, click the stack icon next to layer that you want to modify and click Modify.

    The Edit map layer dialog opens and displays the information in the Layer info and Shapes sections. The information in the Shapes section depends on the way in which you have uploaded the shape.
  4. Select a title for the shape in the Shape title column drop-down list.

    This title is displayed for the shape on the Map view.
  5. Fill up these fields in the Shape hint columns section:

    Field Description
    Custom name Enter a meaningful name for the layer.
    Visible on hint Select whether you want to display the name in the hint on the Map view.
  6. Click Save.

    The changes are saved.

Assign Permissions to a Map Layer

When you upload a shape, by default it is available for all user types. You can change the permissions as to which users can see which shape.

  1. Click Configuration.

  2. In the General section, click Business Rules.

  3. In the Map layers section, click the stack icon next to layer that you want to modify and click Permissions.

    The Select user types dialog appears. By default, all the user types are selected.
  4. To remove access to the selected layer, click the minus icon next to the user type.

  5. To provide access to a layer, click the plus icon. Select the check boxes next to the user types to whom you want to provide access.

  6. Click Save.

    The changes are saved. The updated permissions come into effect the next time the user of the corresponding user type logs in.

Delete a Map Layer

You can delete just a map layer, or a layer and its associated shape files. You can delete the layer using the metadata API, or through the Business Rules page.

  1. Click Configuration > Business Rules.

  2. Go to the Map layers section.

  3. Click the menu on the right against the layer that you want to delete and click Delete.

    The Delete map layer dialog appears.
  4. To delete just the layer, click Delete.

    If you go to the Add map layer dialog box and select the Use already uploaded shapefile option, the shape file that was related to the deleted layer is displayed in the list.
  5. To delete the layer and its associated shape files, select Delete associated shapes and then click Delete.

    If you go to the Add map layer dialog box, the Use already uploaded shape file option is not available. This is because, the shape file that was associated with deleted layer was removed from the Geospatial Database.
  6. Click Save on the Business Rules page.

    Note: Deleting a layer and its associated shape file is possible only through the Core Application interface. The metadata API DELETE method removes only the layers from the database.

Define Bundling Keys for a Visit

Oracle Field Service sends configured notifications for each activity separately. If several activities (appointments) are scheduled on the same day for a customer and you want to send one notification of each kind (for example, day before, reminder, or change notifications) to the customer, then select the Enable Visit Functionality check box to activate the Visit functionality.

Use the Visit Bundling Key field to define the criterion for a visit. The criterion can include an activity property field, where you can set the length of the property values and determine whether the property values are case sensitive. The application compares the values defined in the activity fields against the specified criterion. Activities are grouped together as a visit, only if the values of all visit bundling keys match the specified criterion. To ensure that external system messages are sent properly, you must add a launch condition using visit triggers while configuring message scenarios.
Note: A single activity can appear on the Links tab with a Visit ID if the Visit bundling criteria are met.

When routing is run using Immediate Assignment and if the Bundling setting is used (only available in Immediate Assignment routing), then the Immediate Routing plan uses the Visit Bundling key for route optimization. For example, when you use the activity address as a bundling key and run routing for urgent activities, then routing finds activities that are on the same address as the urgent activity to create visits. For more details, refer to the Immediate Activity Assignment section in the Oracle Field Service Using Routing Cloud Service Guide. After you define the visit bundling keys, click Save to recalculate the existing activities according to the new visit settings. To define bundling keys for a visit:

  1. Click Configuration.

  2. Click Business Rules in the General section.

    The Business Rules page appears.
  3. Select the Enable the Visit functionality check box.

  4. Click the Modify icon.

  5. Click the Plus icon.

  6. Select the required keys.

  7. Click Add.

  8. Use these filters to specify additional criterion for grouping activities:

    • Length: Enter an integer value between 0 to 99. For example, if you enter 5, then the first 5 values of the activity property are considered.

    • Function parameter: Select a parameter to determine whether the activity property values are case sensitive, case insensitive, first word case sensitive, first word case insensitive.

  9. Click Save.

    Note: If there are already visits in the system, and if the visit bundling keys are changed, then after recalculation, the visits no longer matching the keys are split into individual activities. ‘Not Done’ status for a visit is defined as follows:
    • All the work orders in the visit have final statuses.

    • A 'notdone' visit either contains a 'notdone' work order or several work orders with 'completed' and 'cancelled/deleted' statuses.

Example of How to Define Bundling Keys for a Visit

Assume that an installation activity is scheduled for a customer on 21st June, 2016 and is the only notification you send to the customer. The installation activity involves the activities, installing the hardware and installing the software but you want the customer to receive only one notification.

Assume that installing the hardware is assigned to technician William and installing the software is assigned to technician Philip. Both activities are scheduled on the same day at 4 to 5 pm and 5 to 6 pm respectively. Assume these details for the customer:
  • Account number: 123456

  • Address: 77 Discovery Drive, Bozeman, Montana 59718

Since both the activities are performed on the same day for the same customer and at the same location, and the goal is to notify the customer only once, it is necessary to bundle the activities together and schedule a visit. Let us select Account Number and Address properties as the bundling keys from the Configuration, Business Rules page and click Save. Since the values defined in the activity fields (that is, Account number and Address) match the selected criteria (that is, Account Number and Address properties selected as the bundling keys); the activities, installing the hardware and installing the software, are grouped together as a visit. To verify whether the activities are grouped as a visit:

  1. Select Dispatch, Activities.

  2. Select the technician William from the resource tree.

  3. Select the Installing the hardware activity from the dashboard and view the activity details.

  4. Select the Links tab.

    A Visit number is displayed with the Pending status.

  5. Repeat steps 1 through 4 for the Installing the software activity.

Define the Activity Search Fields

The application uses the activity property fields defined in the Search section of the Business Rules page to search for activities.

You can also edit the activity property fields in the Search section of the Business Rules page to define additional search fields to search for activities. For example, assume that the activities are searched using the Name and Account Number activity fields. Now, you want to search the activities using the Address activity field. You can specify an additional search field as follows:
  1. Click Configuration.

  2. Click Business Rules in the General section.

    The Business Rules page displays.
  3. Click the Edit icon for Activity Search fields in the Search section.

    The Activity Search Fields dialog box displays.
  4. Click the Plus icon.

  5. Select the Address field.

  6. Click Add.

  7. Click OK.

    The Address field displays in the Activity Search Fields section.

  8. Click Save.

  9. Click the search icon and click Search Preferences.

    The Search preferences dialog box displays the selected search categories.
  10. Select the by Address check box.

  11. Click the Back to Search button and enter an address, for example, 7700 Technology Way, in the Search field.

    When you search for an activity or a resource, the search fields are selected in the order defined in the Search preferences dialog box. You can perform these tasks in the Search Preferences dialog box:
    • Click the reorder icon to drag and drop the required activity search fields in the list to rearrange the order.

    • Select or deselect the required activity search fields to add or remove the activity search fields.

    • Select an option from the Date drop-down list to refine the activity search results.

    Note: Search uses the first 40 characters of the search string.
The activities matching the specified address display.

Define the Inventory Search Fields

The application uses the inventory property fields defined in the Search section of the Configuration > Business Rules page to search for inventories.

You can also edit the inventory property fields in the Search section of the Business Rules page and define additional search fields to search for inventories. For example, assume that the inventories in the application are searched using the Model and Item Number inventory fields. Now, you want to search the inventories using the Serial Number field. You can specify an additional search field as follows:
  1. Click Configuration.

  2. Click Business Rules in the General section.

    The Business Rules page displays.
  3. Click the Edit icon for Inventory Search fields in the Inventory Search Fields section.

    The Inventory Search Fields dialog box displays.
  4. Click the Plus icon.

  5. Select the Serial Number field.

  6. Click Add.

  7. Click OK.

    The Serial Number field displays in the Inventory Search Fields section.
  8. Click Save.

  9. Click the Search icon.

  10. Enter the Serial Number (for example, 8779808797) in the Search field and click Search.

    The inventory matching the specified serial number displays.
    Note: Search uses the first 40 characters of the search string. Inventory search does not support enumeration type fields.

Capacity Time Intervals

The time interval set consists of time intervals delimited with a comma (","). Time intervals within the time interval set cannot have time period in common (with the only exception of a "point in time" time interval.

Capacity Categories

A Capacity Category is a predefined set of work skills and/or work skill groups and time slots visible to a user who is booking the activities for the customers.

Based on the number of minutes available (Capacity = Initial Quota allocation minus used minutes), the user decides if enough time is available within a time slot to realistically promise a specific service window to the customer. This information is sent to the CSR via Capacity API. Capacity Categories are visible only if you are using the Oracle Field Service Capacity Service module.

Note: The Used Minutes value is calculated based on the exact time (in minutes) from start to end of a working day.
You must enable the Capacity Categories visibility profile permission for each user to access the Capacity Categories window:
  • Read-Only: Select this option to display capacity categories in a view only mode.

  • Read/Write: Select this option to let the user manage Capacity Categories in Oracle Field Service.

If the permissions are not configured for a user type, the activity types will not be visible to the users. Oracle Field Service maps the work skills to assign incoming activities to the resources. In general, many companies define quota for a work skill group rather than for an individual work skill. For example, separate skills are required for installation, un-installing and maintenance of modems, but from a scheduling perspective, quota is defined for all the modem-related works group.

A capacity category can also consist of a single work skill and the minimum required level of the skill level. For example, a category can be created for all the customer-oriented work and a separate group for VIP customers or for highly difficult tasks. The two categories would contain the same work skills but the minimal qualification level in the VIP group is higher. Because of the categories and the multi-skill functionality, the same activity can match several rows in the Quota table and can be added to the Used capacity several times. The duration of this activity will be taken into account for all the capacity categories it matches.

Create a Capacity Category

Create a capacity category to configure work skills, work skill groups, and time slots.

  1. Click Configuration > Capacity Categories.

    The Capacity categories page appears.

  2. Click Add New.

    The Add Capacity Category dialog box appears.

  3. Enter the appropriate information in the following fields:

    The following table describes the fields available on the Add Capacity Category dialog box.

    Option Description
    Name Enter the name of the capacity category. The name is displayed in the list and in the quota matrix. If the application is configured for multiple languages, input boxes will appear for each language.
    Label Specify a label. It is used in the context of APIs and it must conform to a standard naming convention.
    Active Select the Active check box to mark this capacity category as active. Only active capacity categories are used in the quota matrix.
  4. Click Save.

    Once you create the capacity category, you must add work skills, work skill groups and time slots to the category.

Edit a Capacity Category

Edit an existing capacity category to change the status, name, label, work skills, or time slots.

  1. Click Configuration > Capacity Categories.

    The Capacity categories page appears.

  2. Select the check box next to the capacity category that you want to change.

  3. Click the pencil icon in the Name column.

    The Edit Capacity Category dialog box appears.

  4. Change the Name, Label, or Active field. Similarly, click the pencil icon in the Work Skills or Time slots columns and change the required values.

  5. Click Save.

Delete a Capacity Category

Delete a capacity category when you no longer need it.

  1. Click Configuration > Capacity Categories.

    The Capacity categories page appears.

  2. Select the check boxes next to the capacity categories that you want to delete.

  3. Click Delete.

  4. Click OK.

    The selected capacity categories are deleted.

Add or Edit Work Skills Within a Capacity Category

A Capacity Category can contain one or more work skills and each work skill must meet a minimum required level.

  1. Click Configuration.

  2. In the General section, click Capacity Categories.

    The Capacity Categories page appears.
  3. Click the pencil icon in the Work Skills column for the Capacity Category that you want to add or edit.

    The Edit Work Skill dialog box appears.
  4. Select a work skill and add the minimum level of the skill required in the corresponding text box.

    The default value is 1. When the minimum level of a work skill is defined, an activity matches a Capacity Category, only if a required skill level for the activity skill is equal to or more than the level of the Capacity Category.
    Note: If a capacity category contains a group of work skills, the activity matches the category, if it requires at least one of work skills from the group.
Recalculate activities after any edits or updates have been made to apply changes to pending and future activities in the system.

Add or Edit Time Slots Within a Capacity Category

A time slot indicates that the work mentioned in the Capacity Category must be performed in the defined time of the day. Capacity Categories can contain one or more time slot associations.

  1. Click Configuration.

  2. In the Resources, Activities, Inventories section, click Capacity Categories.

    The Capacity Categories page appears.
  3. Click the pencil icon in the Time Slots column for the Capacity Category you want to add or edit.

    The Edit Time Slots dialog box appears.
  4. Select a time slot.

  5. Click Save.

Configure the Display Page

You configure the Display page to change the way the user interface appears to the end user. While you may retain the default settings for most of these settings, you can change a few settings during implementation based on your business needs.

The Display visibility profile permission controls the access to the Display page. You must set this permission for each user type that manages the Display settings. If you don’t configure the permission or the visibility, the Display page is not visible to the user. If you select ReadOnly, Display is placed into a view only mode. If you select Read/Write for this setting, the user can manage Display. To configure the display settings:
  1. Click Configuration.

  2. In the Displays section, click Display.

    The Display page appears.
  3. Complete these fields:

    Field Description
    General
    First day of the week The week that the working week begins.
    Time input The way time is entered in the application-whether it is chosen from a drop-down with fixed increments or is entered manually.
    Allow application to be launched inside iframe Lets you launch the application in an iFrame.
    Remember User Name on Login Screen The control to display the Remember my username check box on the Login page. Selecting the Remember my username check box saves the user name and populates it automatically, when a user uses the same device and browser to log in to the application. This feature is available only for users who have the Internal and LDAP login policies, and not for users who have the SAML or OpenID Connect policies. If a user’s authentication fails, the user name is not populated when the user logs in the next time.
    Enable password reset on Login screen Displays the Can’t sign in link on the Login page, which helps users reset their passwords. Resetting the password is a global feature and is available only for users assigned to an Internal Login Policy. This is not available for users assigned to LDAP, SAML, and OpenID Login Policies. Selecting this check box displays the Email for password reset field.
    Email for password reset The source from which you want to get the email address of the user, who wants to reset their password. This field includes custom properties that can be chosen as the source of the email address to which the recovery email is sent. The custom properties are displayed only if these conditions are satisfied:
    • Entity = User

    • Type = String

    • GUI = Text or Email

    Company time zones
    Time zones The globally available times zones. Use the Edit icon to add the required timezones.
    Company language
    Languages The globally available languages. Use the Edit icon to add the required languages.
    Login screen language The language used on the Login page when accessing the application.
    Mobile settings
    Number of activities per page The number of activities or resources to appear on one page on the mobile device. Default value is 5.
    Number of inventory per page The number of equipment records to appear on one page on the mobile device. Default value is 10.
    Number of days to view on the Calendar screen The number of days to appear on the mobile device at a time. Default value is 14.
    Idle time minimum The threshold under which idle time is not displayed on the Time View.
    Quota settings
    Major Capacity Usage On the Quota grid, quota and minutes used display in brown once used = X% (major) of initial quota. Enter the percent of quota that indicates major capacity usage.

    Expected duration comprises [……] % of quota.

    Critical Capacity Usage On the Quota grid, quota and minutes used display in bright red once used = X% (critical) of initial quota. Enter percent of quota that indicates critical capacity usage.

    Expected duration comprises [……] % of quota.

    Enable Plan column that shows data set in Forecasting Whether a plan created in forecasting is available in the quota management page.
    Alert settings
    Activity has not been started x minutes before the end of Service Window The activity turns red and a Resource Tree warning appears based on the value set in this field. Enter the number of minutes preferred.
    Activity has not been completed x minutes before the end of SLA Window The activity turns red and a Resource Tree warning appears based on the value set in this field. Enter the number of minutes preferred.
    Route has not been started x minutes after the start time of resource work day A warning appears on the resource’s record within the Resource Tree. Enter the number of minutes.
    Activity has not been started x minutes after ETA A warning appears on the resource’s record within the Resource Tree. Enter the number of minutes.
    Activity list settings
    Travel time representation The color for travel time, if a visual of travel time is desired on the Time and List views.
    Resource tree visualization
    Show assistants Shows assistants on the Resource Tree.
    Show teams Shows teams on the Resource Tree.
    Show activity/teamwork counters Shows the count of activities or teamwork on the Resource Tree.
    Map
    Fade resources Whether a resource becomes transparent after geolocation data update.
    Fade resource time The number of minutes after geolocation data update after which a resource’s time becomes transparent.
    Hide resource time The number of minutes after geolocation data update after which a resource’s time is hidden.
    Activity history
    Monitored activity fields The list of activity fields to be monitored. If one of these fields (or properties) is changed, a record is inserted into a corresponding history table. Use the Edit icon to add the required activity fields.
    Monitored inventory fields The list of inventory fields to be monitored. If one of these fields (or properties) is changed, a record is inserted into a corresponding history table. Use the Edit icon to add the required inventory fields.
    History user type The user type to be used to build the identifiers of objects (activities, inventory, and service requests) that are to be logged into the history.
  4. Click Save.

    The settings are saved.

Create a Group or Help Desk

You can communicate with other users in your organization and organize help desk activities using Oracle Field Service Collaboration. You can use the chat window to access data from the application, instead of using the Core Application interface. For example, you can share details about a resource, an activity, or an inventory item, or you can move activities and inventory. Oracle Field Service Collaboration is visible only if it is configured. This procedure describes how to create a group or help desk.

The Collaboration page shows settings that affect the way the user interface appears to the end user. While you may retain the default settings for most of these settings, you can change a few settings during implementation based on your business needs. Access to the Collaboration page is controlled by the Collaboration visibility profile permission. You must set this permission for each user type that manages Collaboration. If you don’t configure the permission or define the visibility for a user type, users of this user type cannot access Collaboration. If you select ReadOnly, Collaboration is placed into a view only mode. If you select Read/Write for this setting, users can manage Collaboration. To create a group or help desk:
  1. Click Configuration.

  2. In the Subsystems section, click Collaboration.

    The Collaboration page appears.
  3. Click the + icon.

    The New group page appears.

  4. Fill up these fields:

    Field Description
    Name Name of the group or help desk you are creating.
    Type Type of group you are creating—options are group and help desk.
    Active Specifies whether the group or help desk is active.
    Description A description for the group or help desk.
  5. If applicable, click the pencil icon in the Groups to collaborate with section to select the groups that the newly created group can collaborate with.

    The Select Groups dialog box appears.

  6. Select the required groups and click OK.

  7. If applicable, click the pencil icon in the Assisting Helpdesks section to select the help desks the newly created group can be assisted by.

  8. Select the help desks and click OK.

  9. Click Save.

Edit or Delete a Group or Help Desk

You can communicate with other users in your organization and organize help desk activities using Oracle Field Service Collaboration. You can use the chat window of Oracle Field Service Collaboration to access data from the application, instead of using the Core Application interface. For example, you can share details about a resource, activity, or inventory item, or you can move activities and inventory. This procedure describes how to edit an existing group or help desk.

  1. Click Configuration.

  2. In the Subsystems And Integrations section, click Collaboration.

    The Collaboration page appears.
  3. Select an existing group or help desk.

  4. To delete, click Delete.

  5. If applicable, click the pencil icon in the Groups to collaborate with section to select the groups that the newly created group can collaborate with.

    The Select Groups window appears.

  6. Select the required groups and click OK.

  7. If applicable, click the pencil icon in the Assisting Helpdesks section to select the help desks the newly created group can be assisted by.

  8. Select the help desks and click OK.

  9. Click Save.

Set Your Language

Oracle Field Service has 29 languages available to be set up as your preferred language. Manage the language setting specific to your company requirements.

Note: A few terms (such as words used in report headers) may not get translated to the language selected as the company's preferred language. The languages Afrikaans, Arabic, French (Canada), Hebrew, Persian, and Spanish (Mexico) are not translated by Oracle and the login pages are in shown in English.
  1. Click Configuration > Display

  2. Under Company Language, click the pencil icon in the Languages field.

  3. On the Languages page, click the plus icon and then select the languages that you want to add as preferred languages.

    These languages are supported:
    • English

    • Afrikaans
    • Arabic
    • Chinese (Simplified)

    • Chinese (Taiwan/Mandarin)

    • Czech

    • Danish

    • Dutch

    • Finnish

    • French (Canada)
    • French (European)

    • German

    • Greek

    • Hindi

    • Hebrew
    • Hungarian

    • Italian

    • Japanese

    • Korean

    • Norwegian

    • Persian
    • Polish

    • Portuguese (Brazil)

    • Romanian

    • Russian

    • Spanish

    • Spanish (Mexico)
    • Swedish

    • Turkish

      The remark, '* Oracle doesn't provide glossary translation.' indicates that the translations are not available for this language and you must add the translations by yourself.

  4. Click Add and then click OK.

  5. From the Login Screen Language drop-down list, select the language in which you want to display the login page.

  6. Click Save.

    The selected language is set.

Create a Filter

Filters have two primary uses—first, filters narrow down lists of activities or resources within the workspace area, based on defined fields and values. These filters are used within the Time, List, and Map views, providing an ad hoc reporting capability. Second, filters within routing plans predefine the information that determines how routing distributes activities across available resources. These filters are commonly set up to differentiate the cost, or value of assigning certain jobs to certain resources, as well as determining the priority of certain types of activities.

The Filters visibility profile permission controls the access to the Filters window. You must set this permission for each user type that manages Filters. If you don’t configure this permission or don’t define the visibility for a user type, users of this user type cannot view the filters that you create. If you select ReadOnly, Filters is placed into a view only mode. If you select Read/Write for this setting, the user can manage Filters. To create a filter:

  1. Click Configuration.

  2. In the Displays section, click Filters.

    The filters listing appears.
  3. Click Add New.

    The Add filter dialog box appears.
  4. Complete these fields:

    Field Description
    Filter The filter name that the users see. Enter the name in English and in all the languages that are active in the application.
    Applicable for The entity type (activity or resource) that the filter pertains to. The entity determines the table fields that can be selected when applying the filter conditions.
    List/Time/Map/Daily The views within which the filter is available.
    Routing Whether the filter is used within routing plans.
    Restriction of Visible Activities Whether you want to restrict filter activities from appearing if resource routes have not been activated or a working day has not yet begun. This configuration is related to the User Type. Once the filter is configured, apply the filter as a visibility restriction filter for user type.
    User Types The user types that the filter is available for. This field is displayed if you select the List/Time/Map/Daily check box. Use the arrow buttons to move the user types between the Available and Selected columns.
  5. Click Add.

    The filter is saved.

You must add conditions for the filter. If no conditions are added, the filter does not work.

Add a Filter Condition

Filter conditions help you further narrow down the activity you want to search for. For example, you can have a condition to select activities based on work zones.

  1. Click Configuration, Filters.

    The Filters page is displayed.

  2. Locate the filter you want to add a condition to.

  3. Click Conditions in the Actions column.

  4. Click Add New at the top of the page.

    The Add filter condition dialog box appears.

  5. Complete these fields:

    Field name Action
    Field Choose one or more activity or resource-based criteria on which to base the filter.
    Dynamic Select the box if you want the user to type a value for the field that the condition is for.
    Conditions Select one or more options to represent how the field selected above relates to the Value entry.
    Value These are the options that can be associated with the Field chosen for this condition. If multiple values are applicable for this condition to be met, then add them to the Selected column. From the list of available values, click to select and then click the >> button. The selected item moves to the Selected column. These rules apply to enumeration fields:
    • Any field and property used in the application can serve as a filter condition.

    • You must populate the value for the field and property other than enumerated fields manually.

    • The condition value supports CSV format, such as 1, 2, 3, 4,, "1,1,1", "2,s", and "(""test"")".

  6. Click Add.

  7. Navigate to the Work Area and verify that the filter is listed in the View drop-down menu.

  8. Test the filter to ensure that it meets your requirements.

Delete a Filter Condition

When a filter condition is no longer needed, you can remove it from the application.

  1. Click Configuration. Click Filters from the Displays section.

  2. Find the filter that has the condition you want to delete from and click the Conditions link.

  3. Select the check boxes next to the condition that you want to delete.

  4. Click Delete above the list of conditions.

  5. Click OK.

Delete a Filter

When you don't need a filter anymore, you can remove it from the application.

  1. Click Configuration. Click Filters from the Displays section.

  2. Select the check boxes next to the filters that you want to delete.

  3. Click Delete.

  4. Click OK.

Glossary Entries

Use the Glossary to configure the default names of UI elements to your business needs. For example, instead of the default term for the Activity Status, Completed, you can use the glossary to configure the term to display as Done.

You can configure the description of a user-interface element, only if the element corresponds to a glossary item in the Oracle Field Service glossary.

The changes made to glossary references are global, that is, the change is consistent for all users. However, the same glossary entry might belong to different categories or sub categories. For example, the glossary entry, Not Done belongs to the categories, Activity Status, Activity History Operation, Notification Trigger Name, and Action Link. If you modify the glossary entry, Not Done that belongs to the category, Activity Status, then the change does not affect other categories.
Note: The glossary entries for the Screen Configuration (Application screens and Collaboration and Identifiers) categories are configured for the selected user types.

The Glossary Visibility Profile permission that controls the access to the Glossary page for a User Type is set using the Company Configuration context in the Screen Configuration, Application screens section. Only User Types that have Read/Write access can modify the glossary.

These columns display on the Glossary page:
  • Category: Displays the category and the sub category, if available, in the format, <Category:Subcategory>. For example, Activity: First Manual Operation.

  • Label/ID: The label/ID of the glossary entry displays. If label is not available, the ID displays. You cannot change labels in the glossary.

  • Columns for each language: The selected languages are displayed. See Add an Active Language.

You can click the text highlighted in red on any of the Language column to view the number of missing glossary entries.

When you update one of the missing glossary entries, the red highlight on the text box disappears and the count in the Language column is updated. If no entry is missing, the warning text on the column header disappears.

Click the Search icon in the search field to list the glossary entries. You can select a specific category from the drop-down list next to the search box and enter a term in the Search field to search for the required glossary entries.

By default, the original text for all glossary entries is displayed. When you modify the original text of a glossary entry and click Save, the modified text is overwritten. However, the original text is still visible, when you hover the mouse over the modified text.

Modify a Glossary Entry

Oracle Field Service glossary items have a unique identifier referred to as placeholder IDs. The Placeholder ID that displays next to an UI element lets you identify the correct glossary item that you want to edit in the Glossary page. For example, you can use Show instead of View.

You can also modify the description of an UI element using an in-context editor, so that you need not access the Glossary page. This example explains how to modify the description of a UI element, View, using placeholders and in-context editor. To modify a glossary entry:
  1. Select your user name (for example, Admin) at the top right corner.

  2. To modify the description of each UI element using placeholders:

    1. Select My Display.

    2. Select the Show Placeholder ID check box.

    3. Click OK and refresh the page.

      Each UI element that corresponds to an Oracle Field Service glossary item in the application displays an ID next to them.
    4. Select Dispatch,Activities.

    5. Make a note of the placeholder ID (for example, 8047) for the UI element, View.

    6. Click Configuration.

    7. Click Displays, Glossary.

    8. Enter the Placeholder ID in the search field and click the Search icon.

      The glossary entry displays.
    9. Select English as the language and enter the term, Show in the field.

    10. Click Save.

      The glossary entry is modified and you can view the original text, View when you hover the mouse over the modified term, Show.
  3. To modify the description of each UI element using the in-context editor:

    1. Repeat steps 1 to 2.c from the above procedure.

    2. Select your user name (for example, Admin) and select Glossary Editor is Off.

      The in-context glossary editor is turned on.
    3. Select Dispatch, Activities.

    4. Select View.

      An on-screen glossary editor displays.
    5. Enter the term, View in the English field.

    6. Click Save.

    7. Deselect Glossary Editor is Off and the Show Placeholder ID check box from the My Display page.

    8. Refresh the page.

      The modified description displays.

Export and Import Glossary Items

You can export the glossary entries to a .csv file to achieve these goals:
  • Translate a list of glossary entries to one of the selected languages that is set using the Languages button.

  • Modify a list of glossary entries.

    Note: It is recommended that you use a text editor to update the glossary terms. don't use Microsoft Excel, as it converts the .csv file from a comma-delimited file with quote qualifiers to a comma-delimited file without quote qualifiers.

You can simultaneously update a list of glossary entries and import the updated list into the application. This example explains how to export a list of glossary entries related to the Activity Hint Category, and import the modified entries into the application. To export glossary entries:

  1. Click Configuration.

  2. Click Displays, Glossary.

  3. Select Activity Hint as the Category from the drop-down list.

    The entries related to Activity Hint display.
  4. Click Export.

    The Export dialog displays and by default, the languages that display on the Glossary page are selected. You can also export the entries to any of the deselected languages. To add a language, see Add an Active Language.
  5. Select the Filtered option to only export the entries related to the Category, Activity Hint. Or, select the All option to export all the glossary entries.

  6. Click Export.

  7. Save the file in the .csv format, for example, test.csv.

  8. Open test.csv, modify the required entries in the English (en-US) and Spanish (es-ES) columns, and save the file.

  9. Click Import on the Glossary page, select test.csv, and click Import.

  10. Click Save.

    The modified entries display in the English and Spanish columns.

Add an Active Language

You can select the active languages, that is, the languages that you want to display on the Glossary page without accessing the Company Language setting. Based on your selections, the Language columns (drop-down lists that let you toggle among the selected languages) are updated.

Note: You can only view two columns on the Glossary page.

To add an active language:

  1. Select Languages from the Glossary page.

  2. Click the Plus icon.

  3. Select the language, for example, Spanish and click Add.

    The selected language displays in the Languages list.
  4. Click OK.

The selected language, Spanish displays as an option in both the Language columns.

Edit Property Descriptions

You can edit the description for properties for each user type and for each page separately using these categories:
  • Screen Configuration - Application screens

  • Screen Configuration - Collaboration and Identifiers

Each category has a sub category that is associated with the respective page within Screen configuration. For example, the Activity fields sub category for export that belongs to the Screen Configuration – Manage category is associated with the Activity fields for Export page that belongs to the Screen Configuration – Manage category within the Configuration, User Types page.
Note: If you share a page configuration across multiple user types, then the properties of that page configuration are also shared. So, any change to the description of a property of that page configuration, affects all user types.
Let's say you share the page configuration that belongs to the Administrator user type across the Technician and Field Engineer user types. The properties of the page configuration that belongs to the Administrator user type are also shared.

Assume that the Activity fields for Export page that belongs to the Administrator user type has a property named Work Order and the page is shared across the Technician and Field Engineer user types. When you edit the glossary entry for the Work Order property, the changes are also applied for the Technician and Field Engineer user types.

By default, the Glossary page displays all properties for each page within Screen configuration. If there are custom names for any of the user types, then the original and custom names for the property are displayed in a comma-separated format for each language.

Example of Editing a Property Description

This example shows how to add a custom name, Job Code to the Technician user type, for the Work Order property in the Activity fields for export page that belongs to the Screen Configuration – Manage category.

  1. Click Configuration > Glossary.

  2. Select Screen Configuration – Manage from the drop-down list and click the Search icon.

    The properties related to Screen Configuration – Manage display.
  3. Click the Edit icon in the language column that is displayed for the Work Order property for the Screen Configuration - Manage: Activity fields for export category.

    If you have edited the property before, the original name and the user types to which the current name applies are displayed. If you have not edited the property so far, all the user types are displayed.
  4. Click the Plus icon and select the user type, Technician.

    The Edit Custom Names for User Types page and the Plus icon display when there are custom names for user types. If there are no custom names for user types, the Add page displays when you click the Edit icon.
  5. Click Add.

  6. Enter the custom name, Job Code in the field.

  7. Click OK.

    The custom name Job code displays with the original name Work Order, in a comma-separated format for each language.

Inventory Types

Inventory Type helps you distinguish between serialized and non-serialized inventory.

Access to the Inventory Type window is controlled by the Inventory Types visibility profile permission. You must set this permission for each user type that you want to manage Inventory Types. If the action is not configured for the user type or if no visibility is defined, Inventory Types will not be visible to the user. If you select ReadOnly, Inventory Types is placed into a view only mode. If you select Read/Write for this setting, the user can manage Inventory Types.

Add an Inventory Type

You can create serialized inventory and non-serialized inventory types.

  1. Click Configuration.

  2. In the Resources, Activities and Inventories section, click Inventory Types.

  3. Click Add new.

    The Add inventory type dialog box appears.
  4. Complete these fields:

    Field Description
    Label Enter a unique identifier for this inventory type.
    Active Select this check box to make the inventory type available in drop-down lists.
    Non Serialized Select this check box if the inventory type is non-serialized.
    Decimal quantity Select this check box if you want users to add decimal quantity of the inventory. For example, 1.5 liters. This check box is displayed only if you select the Non-serialized check box.
    Quantity precision Enter the number of digits you want to display after the decimal. This check box is displayed only if you select the Decimal quantity check box.
    Supports required inventory Select this check box to make the inventory type required for selected activities.
    Model Property If desired, select additional characteristics for this inventory type from the drop-down list.
    Name Enter a name for this inventory type in each appropriate language field.
    Unit of measurement If this inventory type is non-serialized, enter a unit of measure. Use a language and a unit of measure appropriate for the country in which this inventory type will be used.
  5. Click Save.

Activate or Deactivate an Inventory Type

Inventory Type helps you distinguish between serialized and non-serialized inventory. You can deactivate an Inventory Type when you don’t use it any more.

  1. Click Configuration.

  2. Select Inventory Types from the Resources, Activities and Inventories section of the menu.

  3. Select the check box next to inventory type(s) that you want to activate or deactivate.

  4. Click Activate or Deactivate.

  5. Click OK.

Link Templates

Link Templates are link profiles containing link type, time between activities constraints, scheduling constraints, and assignment constraints. Links between the activities are created with the help of Link Templates.

Linked activities ensure scheduling and detailed planning for complicated, multi-step tasks, which may potentially involve different resource types, different times, and time constraints. Configuring all these link constraints in a multi-step task allows our routing engine to assign and schedule activities while meeting all of the requirements.

The Link Templates page includes the list of link types that exist in the application. You can edit the existing links and add new ones. You cannot remove the existing activity link types, you can only deactivate them.

Access to the Link Templates page is controlled by the Link Templates visibility profile permission. You must set this permission for each user type that you want to manage Link Templates. If the action is not configured for the user type or if no visibility is defined, Link Templates is not visible to the user. If you select ReadOnly, Link Templates is available in the view only mode. If you select Read/Write for this setting, the user can manage Link Templates.

Add a Link Template

Link Templates are link profiles that describe how activities are linked. The templates contain the type of link, constraints for the time between activities, scheduling constraints, and assignment constraints. Links between the activities are created with the help of Link Templates.

  1. Click Configuration.

  2. In the General section, click Link Templates.

  3. Click Add Link Template.

    The New Link Template dialog box is displayed.
  4. Select the appropriate icon that represents the way in which you want to link activities.

    The fields below the icons change based on your selection.
  5. Complete these fields:

    Field Description
    Minimum interval Minimum time interval between activities. Select one of the options:
    • Adjustable: The time interval is adjustable with the specified default value.

    • Non-adjustable: The time interval is non-adjustable with the specified predefined value.

    Maximum interval Maximum time interval between activities. Select one of the options:
    • Adjustable: The time interval is adjustable with the specified default value.

    • Non-adjustable: The time interval is non-adjustable with the specified predefined value.

    • Unlimited: The time interval is unlimited, with no restrictions.

    Assignment constraints Whether there are any constraints in assigning the activities to resources. Click Different resources if the linked activities can be performed by different resources. Click Same resource if the linked activities must be performed by the same resource.
    Scheduling constraints Whether there are any constraints in scheduling the activities. Click Different days if the linked activities can be performed on different days. Click Same day if the linked activities must be performed on the same day.
    Link for the 1st activity Specifies translations for the first activity. English is set as a default language, unless other languages are specified. You must also specify the label for this link which will be used by external applications.
    Link for the 2nd activity Specifies translations for the second activity. English is set as a default language, unless other languages are specified. You must also specify the label for this link which will be used by external applications.
    Label A unique identifier for this Link template.
    Status Whether this activity link type is available for selection as an option on the Add link page.

Login Policies

Login Policies determine the authentication method and options for users to access the application.

There are five types of authentication methods:

Table

Authentication Method Description
Internal The internal authentication method (BasicHTTP) is a good solution for small companies with relatively few user credentials, which can be stored in the application database.
LDAP The LDAP (Lightweight Directory Access Protocol) authentication method is similar to the internal method. The only difference is that the users' credentials are stored outside Oracle Field Service in an external LDAP server. This method can be used by companies that prefer to store their user data in an external server to increase security. When the LDAP authentication is used, the user enters their credentials into Oracle Field Service, which then passes them to the LDAP server for verification. To enable LDAP authentication, a software that supports LDAP v3 must be installed and configured on the customer's back-end server. Examples of such software are: Active Directory, OpenLDAP.
SAML The SAML (Security Assertion Mark-Up Language) authentication method is an SSO method, involving authentication data exchange between the user, the service provider (SP) and the identity provider (IdP). The user wishing to access the services of the service provider has to pass the authentication by the identity provider, which asserts the user's identity to the service provider. The user's data is stored with the identity provider and is verified by the user's credentials. If the user authentication is successful, the service provider verifies the user's login policy and grants access to the application. One user can be associated with only one login policy and, therefore, its data can be stored with only one identity provider. The application supports SAML 2.0 protocol, therefore, you can use any SAML 2.0 identity provider. The identity provider details must be used in configuring the SAML Login Policy.
IDCS for Web SSO You can use Oracle Identity Cloud Service (IDCS) as an identity provider for web SSO. This option helps customers store user credentials in a different store instead of Oracle Field Service. This option is part of the SAML authentication option, and you can upload the metadata as an XML file.
OpenID Connect With the OpenID Connect authentication method, a user uses the account created with an OpenID Connect Identity Provider to log in to any website supporting the OpenID Connect authentication. The user registers the OpenID Connect URL with the OpenID Provider, which becomes the user's identifier. OpenID Connect can be a method of choice for companies preferring cloud data storage and using the same credentials to access multiple websites.

Generally, the authentication method used depends on the company's business principles and requirements. In most cases, a company uses one authentication method, although, use of several authentication methods within the same company is technically possible.

Add a Login Policy

Login policies determine the authentication method and options for users to access Oracle Field Service. The application includes a default login policy, however, you can add multiple policies with multiple authentication methods.

Before you implement OpenID Connect: Create or register Oracle Field Service as an application in your identity provider. Get the Configuration URL, Logout URL, Client ID, and Client secret from the identity provider. Further, define an attribute that will be used for the username.
  1. Click Configuration.

  2. In the Users and Security section, click Login Policies.

  3. Click Add new.

    The Add Policy dialog box appears.
  4. Complete these fields:

    Field Action
    Label Enter a unique identifier label. For SAML login policy, enter only alphabets, numbers, and undersrores ( _ ).
    Policy name Enter a name for this policy. Enter the name in English and in all the languages that are active in the application.
    Authenticate using Select the type of authentication method used for this login policy.
    These fields are displayed for Internal authentication method:
    Max login attempts Enter the number of invalid login attempts after which the user is blocked. When this field is set to 0 (zero), the feature is disabled. However, disabling this feature is not recommended for security reasons.
    Login block timer Enter the number of minutes during which the user remains blocked after reaching the maximum number of invalid login attempts.
    Force password change after Enter the number of days after which the user must change their password to access the application. When this field is set to 0 (zero), the feature is disabled.
    Note: If the customer's LDAP server allows setting the period of forced password change, it is recommended that the period set in the application is shorter than the one set on the LDAP server. This way, the password changes initiated by the application occur earlier than those initiated by the LDAP server which ensures correct and reliable performance.
    User activity relogin time Enter the duration of the idle time after which the user is prompted to re-enter the password upon an attempt of any action in the application.
    Relogin timeout Enter the period after which the user is prompted to re-enter the password regardless of whether the user was active or not.
    Max sessions Enter the maximum number of simultaneous sessions allowed to the user.
    Min password length Enter the minimum number of characters in the password. Default is 8.
    Password must contain uppercase and lowercase letters Select whether the password must contain alphabets. This option is selected by default.
    Password must contain digits Select whether the password must contain numbers. This option is selected by default.
    Password must contain special symbols Select whether the password must contain special characters and symbols. This option is selected by default.
    Password must not contain personal details Select whether the password must not contain personal details such as the user’s first name or last name. This option is selected by default.
    Password must differ from old password Select whether the password must be different from a previous password. This option is selected by default.
    Allow access only for certain IP addresses Select whether you want to restrict access to specific IP addresses. By default, a login policy is created without any restrictions to the IP addresses from which the user may log in. Select the check box to enable the restriction. When this check box selected, the Allowed IP address list field appears, where you can enter the IP addresses that can access the application.
    These fields are displayed for the LDAP authentication method, along with the fields listed earlier:
    LDAP server URL Enter the actual host name or IP address of the LDAP server.
    LDAP DN pattern If you want to select the LDAP server is MS Active Directory check box, enter the part of the UPN (User Principal Name) common among the users. In this case the LDAP DN pattern must always contain the UPN pattern. UPN (User Principal Name) is a string of characters used to represent a resource available in Active Directory. It should be used when communicating with MS Active Directory servers. An example of this field value is %s@test.corp, where %s is a special placeholder to be substituted with the user's login. If the LDAP server is MS Active Directory check box is not selected, this field contains the common path to the LDAP tree for the users, their DN pattern. DN (Distinguished Name) is a string of characters used to represent a resource available in the LDAP directory. An example of this field value is cn=%s,dc=example,dc=com, where %s is a special placeholder to be substituted with the user's login in the application.
    LDAP server is MS Active Directory Select whether the LDAP server is a MS Active Directory.
    These fields are displayed for the SAML authentication method:
    Specify SAML IdP Select the way in which you want to select the SAML identity provider. The options are:
    • Upload metadata XML

    • Specify metadata URL

    • Oracle IDCS

    • Manual populate

    IdP Metadata XML This field is displayed if you select Upload metadata XML in the Specify SAML IdP field. Click Upload to upload the XML file that contains the metadata details for the identity provider. If the uploaded file is incomplete, or does not contain the details in the proper format, the message, Cannot download metadata from the specified XML: XML parser error is displayed. Contact your Identity Service Provider to get this metadata XML. Ensure that the XML includes or conforms to this information:
    • Metadata XML must be in accordance with SAML 2.0 specifications.

    • The file contains "SAML Issuer" (parameter "entityID" of the node "EntityDescriptor").

    • The file provides identity provider certificate (nodes "md:EntityDescriptor/md:IDPSSODescriptor/KeyDescriptor/KeyInfo/X509Data/X509Certificate/").

    IdP Metadata URL This field is displayed if you select Specify metadata URL in the Specify SAML IdP field. Type the URL from which you want to take the SAML metadata details for the identity provider. If the URL is unresolved, the message, Cannot download metadata from the specified URL: no route to host is displayed.
    IDCS Metadata XML This field is displayed if you select Oracle IDCS in the Specify SAML IdP field. Click Upload to upload the XML file that contains the metadata details for Oracle IDCS. Contact your implementation consultant for more details on Oracle IDCS.
    OFS Metadata XML Click to download the Oracle Field Service metadata XML. You must pair your identity provider with Oracle Field Service. Use the downloaded XML file to register Oracle Field Service with your identity provider.
    Max sessions Enter the maximum number of simultaneous sessions allowed to the user.
    SAML issuer Enter the identifier used to identify asserts from the Identity provider (IdP). It can be any string provided by IdP, not only URL. It is used for IdP and Service provider (SP) initiated connections.
    SAML identity provider certificate Enter the IdP public key used to sign requests.
    SAML identity provider login URL Enter the IdP URL to redirect to for login. It is needed only for SP initiated logins.
    SAML identity provider logout URL Enter the IdP URL to redirect to for logout. It is needed only for SP initiated logins.
    SAML attribute containing username Enter the SAML assertion attribute name where IdP must store the user name (login name for Oracle Field Service). Example:
    [saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrnameformat:
    basic"]
    [saml:AttributeValue xsi:type="xs:string"]dispatcher[/saml:AttributeValue]
    [/saml:Attribute]
    
    If it is empty then Oracle Field Service gets the user name from the Name Identifier element of Subject statement. Example:
    [saml:Subject]
    [saml:NameID
    SPNameQualifier="https://sp.com/sp/module.php/ saml/sp/metadata.php/ default-sp"
    Format="urn:oasis:names:tc:SAML:2.0:nameidformat:
    persistent"]dispatcher[/saml:NameID]
    [/saml:Subject]
    Generate metadata using instance URL Select this option to construct the URL to log in using the instance URL. This is the recommended way and is the default option for all new SAML Login Policies. The URL for your organization is based on your instance name and is displayed under this field in the application.
    Generate metadata using login.etadirect.com Select this option to construct the URL to log in as login.etadirect.com. This is the non-recommended way and the option selected for existing SAML Login Policies.
    These fields are displayed for the OpenID authentication method:
    Max sessions Enter the maximum number of simultaneous sessions allowed to the user.
    OpenId identity provider login URL Enter the Identity Provider URL to start authentication.
    OpenId logout URL Enter the URL to which the user is redirected after logout. It may be the URL for logout from the Identity Provider.
    OpenId attribute containing username Enter the name of the OpenId attribute where the Identity Provider should store the user's name (login name for Oracle Field Service). Example:

    http://axschema.org/contact/email (This attribute returns the user's email). The attribute must have a unique value for each user.

    These fields are displayed for the Open ID Connect authentication method:
    Max sessions Enter the maximum number of simultaneous sessions allowed to the user.
    Configuration login URL Enter the Identity Provider URL to start authentication.
    Logout URL Enter the URL to which the user is redirected after logout. It may be the URL for logout from the Identity Provider.
    Attribute containing username Enter the name of the OpenId attribute where the Identity Provider must store the user's name (login name for Oracle Field Service). Example: email.
    Client ID Enter the value of the field containing data from registered OpenID provider (for example, Client ID).
    Client secret Enter the value of the field containing data from registered OpenID provider (for example, Client Secret).
    Use instance URL for redirect to OFS Select this option to construct the URL to be redirected to the application using the instance URL. This is the recommended way and is the default option for all new OpenID Connect Login Policies. The URL for your organization is based on your instance name and is displayed under this field in the application.
    Use login.etadirect.com for redirect to OFS Select this option to construct the URL as login.etadirect.com. This is the non-recommended way and the option selected for existing OpenID Connect Login Policies.
  5. In your OpenID application, configure a link back URL. Use the URL displayed in this dialog box for the option that you have selected.

    Your Identity Provider uses this link to redirect users to Oracle Field Service upon successful login.
  6. Click Add.

    The application generates the metadata based on the options you have selected. Use this metadata to link your identity provider with the instance. Note down the instance URL that you must use when setting up an external identity provider.

Sample Metadata XML File for SAML Identity Provider

Sample metadata XML file for SAML identity provider:
<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://idp-saml.ua3.int/simplesaml/saml2/idp/metadata.php">
  <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIID7TCCAtWgAwIBAgIJANn3qP9lF7M3MA0GCSqGSIb3DQEBCwUAMIGMMQswCQYDVQQGEwJVQTEXMBUGA1UE
		  CAwOS2hhcmtpdiBSZWdpb24xEDAOBgNVBAcMB0toYXJrb3YxDzANBgNVBAoMBk9yYWNsZTEYMBYGA1UEAwwPc3RzeWJvdi12bTEudWEzMScw
		  JQYJKoZIhvcNAQkBFhhzZXJnaWkudHN5Ym92QG9yYWNsZS5jb20wHhcNMTUxMjI1MTIyMjU5WhcNMjUxMjI0MTIyMjU5WjCBjDELMAkGA1UE
		  BhMCVUExFzAVBgNVBAgMDktoYXJraXYgUmVnaW9uMRAwDgYDVQQHDAdLaGFya292MQ8wDQYDVQQKDAZPcmFjbGUxGDAWBgNVBAMMD3N0c3lib
		  3Ytdm0xLnVhMzEnMCUGCSqGSIb3DQEJARYYc2VyZ2lpLnRzeWJvdkBvcmFjbGUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCA
		  QEAw4OFwuUNjn6xxb/OuAnmQA6mCWPY2hKMoOz0cAajUHjNZZMwGnuEeUyPtEcULfz2MYo1yKQLxVj3pY0HTIQAzpY8o+xCqJFQmdMiakb
		  PFHlh4z/qqiS5jHng6JCeUpCIxeiTG9JXVwF1ErBEZbwZYjVxa6S+0grVkS3YxuH4uTyqxskuGnHK/AviTHLBrLfSrbFKYuQUrXyy6X22wpzo
		  bQ3Z+4bhEE8SXQtVbQdy7K0MKWYopNhX05SMTv7yMfUGp8EkGNyJ5Km8AuQt6ZCbVao6cHL2hSujQiN6aMjKbdzHeA1QEicppnnoG/Zefyi/
		  okWdlLAaLjcpYrjUSWQJZQIDAQABo1AwTjAdBgNVHQ4EFgQUIKa0zeXmAJsCuNhJjhU0o7KiQgYwHwYDVR0jBBgwFoAUIKa0zeXmAJsCuNhJj
		  hU0o7KiQgYwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAJawU5WRXqkW4emm+djpJAxZ0076qPgEsaaog6ng4MLAlU7RmfIY/
		  l0VhXQegvhIBfG4OfduuzGaqd9y4IsQZFJ0yuotl96iEVcqg7hJ1LEY6UT6u6dZyGj1a9I6IlwJm/9CXFZHuVqGJkMfQZ4gaunE4c5gjbQA5/
		  +PEJwPorKn48w8bojymV8hriqzrmaP8eQNuZUJsJdnKENOE5/asGyj+R2YfP6bmlOX3q0ozLcyJbXeZ6IvDFdRiDH5wO4JqW/ujvdvC553y
		  CO3xxsorB4xCupuHu/c7vkzNpaKjYdmGRkqhEqBcCqYSxdwIFc1xhOwYPWKJzgn7pGQsT7yNJg==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIID7TCCAtWgAwIBAgIJANn3qP9lF7M3MA0GCSqGSIb3DQEBCwUAMIGMMQswCQYDVQQGEwJVQTEXMBUGA1
		  UECAwOS2hhcmtpdiBSZWdpb24xEDAOBgNVBAcMB0toYXJrb3YxDzANBgNVBAoMBk9yYWNsZTEYMBYGA1UEAwwPc3RzeWJvdi12bTEud
		  WEzMScwJQYJKoZIhvcNAQkBFhhzZXJnaWkudHN5Ym92QG9yYWNsZS5jb20wHhcNMTUxMjI1MTIyMjU5WhcNMjUxMjI0MTIyMjU5WjCB
		  jDELMAkGA1UEBhMCVUExFzAVBgNVBAgMDktoYXJraXYgUmVnaW9uMRAwDgYDVQQHDAdLaGFya292MQ8wDQYDVQQKDAZPcmFjbGUxGDA
		  WBgNVBAMMD3N0c3lib3Ytdm0xLnVhMzEnMCUGCSqGSIb3DQEJARYYc2VyZ2lpLnRzeWJvdkBvcmFjbGUuY29tMIIBIjANBgkqhkiG9w0B
		  AQEFAAOCAQ8AMIIBCgKCAQEAw4OFwuUNjn6xxb/OuAnmQA6mCWPY2hKMoOz0cAajUHjNZZMwGnuEeUyPtEcULfz2MYo1yKQLxVj3pY0HT
		  IQAzpY8o+xCqJFQmdMiakbPFHlh4z/qqiS5jHng6JCeUpCIxeiTG9JXVwF1ErBEZbwZYjVxa6S+0grVkS3YxuH4uTyqxskuGnHK/
		  AviTHLBrLfSrbFKYuQUrXyy6X22wpzobQ3Z+4bhEE8SXQtVbQdy7K0MKWYopNhX05SMTv7yMfUGp8EkGNyJ5Km8AuQt6ZCbVao6cHL2h
		  SujQiN6aMjKbdzHeA1QEicppnnoG/Zefyi/okWdlLAaLjcpYrjUSWQJZQIDAQABo1AwTjAdBgNVHQ4EFgQUIKa0zeXmAJsCuNhJjhU0o
		  7KiQgYwHwYDVR0jBBgwFoAUIKa0zeXmAJsCuNhJjhU0o7KiQgYwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAJawU5WRXq
		  kW4emm+djpJAxZ0076qPgEsaaog6ng4MLAlU7RmfIY/l0VhXQegvhIBfG4OfduuzGaqd9y4IsQZFJ0yuotl96iEVcqg7hJ1LEY6UT6u6d
		  ZyGj1a9I6IlwJm/9CXFZHuVqGJkMfQZ4gaunE4c5gjbQA5/+PEJwPorKn48w8bojymV8hriqzrmaP8eQNuZUJsJdnKENOE5/
		  asGyj+R2YfP6bmlOX3q0ozLcyJbXeZ6IvDFdRiDH5wO4JqW/ujvdvC553yCO3xxsorB4xCupuHu/c7vkzNpaKjYdmGRkqhEqBcCqYSxd
		  wIFc1xhOwYPWKJzgn7pGQsT7yNJg==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp-saml.ua3.int/simplesaml/saml2/idp/SingleLogoutService.php"/>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp-saml.ua3.int/simplesaml/saml2/idp/SSOService.php"/>
  </md:IDPSSODescriptor>
  <md:ContactPerson contactType="technical">
    <md:SurName>Administrator</md:SurName>
    <md:EmailAddress>name@emailprovider.com</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

Organizations

An organization is an entity comprising multiple people, tools, and vehicles that collectively operate as a unit toward a common goal. In other words, an organization is either a main company, a subdivision (Line of Business of an organization), or a third-party company that has a contract with the main company. An organization can have buckets, organization units, field resources, tools or vehicle associations.

An Organization can have buckets, organization units (Org Units), field resources, tools or vehicle associations. You must create an organization before adding any type of resource. There is one default organization and you can create additional organizations (in-house and contractor) to meet your operational needs. For example, if XYZ Inc., is the main organization, XYZ East Coast and XYZ West Coast could be subdivisions. The resources that are directly employed with the organization are known as in-house resources. The resources that are employed by a third-party company that subcontracts work are known as contractors. It is recommended that you create an organization for each contractor company. If the main organization cannot directly assign activities to contractor resources for legal reasons, it can assign activities to a bucket that contains contractors. Further, a field resource, tool or vehicle will automatically inherit the parent’s Organization, while a bucket or organization unit can be changed to any defined Organization in the system.

Create, Edit, or Delete Organizations

An Organization is a main company, a subdivision (Line of Business of an Organization), or a third-party company that has a contract with the main company. An Organization can have buckets, Organization units, field resources, tools, or vehicle associations. You can create, edit, or delete Organizations.

  1. Click Configuration > Organization.

    The Organizations page appears.
  2. Click Add New.

    The Add Organization dialog box appears.
  3. Enter the name of the Organization in the Name field. Enter the names in the corresponding language fields for languages other than English.

  4. Enter a label for the Organization in the Label field.

    This label will be used as the Organization identifier in APIs.
  5. Select the type of Organization from the Type drop-down list.

    The Organization type can be in-house or contractor.
  6. Click OK.

    The Organization is added to the list of Organizations.
  7. To edit an Organization, click the Organization on the Organizations page.

    The Edit Organization dialog box appears. Edit as required and click Submit.
  8. To delete an Organization, click Remove on the Organizations page.

    You can remove only those Organizations that don't have field resources, tools, or vehicles assigned to them.

Message Scenarios

A Message Scenario consists of one or more scenario steps, which determine the message content, recipients, delivery channels, and business rules. While each Message Scenario has at least one start step, you can configure multiple inner steps to execute different actions based on the results of the preceding steps. The intent is to ensure that the right people or systems receive the expected notifications, while considering all potential circumstances.

When you want to use Message Scenarios for time-based notifications (for example, notifications to customers) the recommendation is to use Reminders, Alerts, or Visit selections in the Launch Conditions. For other Launch Conditions (for example, Route, Activity, Inventory, and Service Requests) the recommendation is to use the Core API/Events REST API for integration with Oracle Field Service.
Note: Because the messages go to your customers, you must test them carefully and thoroughly to ensure that the launch conditions, scenarios, steps, and channels are set up correctly. For more information about Launch conditions warnings and notes, Scenario Steps elements, Channel errors, Supported variables within the body of the message, refer to Oracle Field Service Message Scenario Configuration Guide.

Create a Message Scenario

A message scenario is a set of rules that specify how to process a message to an external application, or to customers when a launch condition occurs. A launch condition is triggered by a predefined event, for example, when a reminder notification must be sent to a customer 60 minutes prior to a resource’s estimated arrival time.

  1. Click Configuration.

  2. Click Message Scenarios in the Subsystems And Integrations section.

    The Message Scenarios page displays.

  3. Click the Plus icon in the left pane.

    The Add Message Scenario dialog box displays.
  4. Enter Route Not Activated in the Name field.

  5. Select a date from the Active From field.

  6. Click OK.

    The Route Not Activated message scenario displays on the left pane.

Define the Settings for a Scenario Step

The Settings tab enables you to define the general settings for a message step which includes these settings:

  • Step Info section: Define the type of the message step, intended recipient, and the delivery method.

  • Notification Time section: Define when to send the message (for example, day of event or for how many days) and the time interval when the messages are sent.

Field Description
Step Info section
Name Enter the name of the step that displays in the Scenario steps section.
Type Select the type of step, Start or Inner. Start steps are the first steps that occur when a scenario is initiated. An inner step is run after a preceding step is completed.
Delivery Channel Select the message agent for delivering the message. Options: Email, Set Property, user-defined channel, Collaboration.
Note: If you select collaboration as the delivery channel, see Use Collaboration as a Delivery Channel
Recipient The options available varies based on the selected delivery channel (Email, Set Property, user-defined channel, or Collaboration).

Select the intended recipient (Customer, Resource, Dispatcher, or use static address) of the message.

By default, the recipient address is fetched from the activity or resource fields for the options, Customer, Resource, or Dispatcher.

However, if you select Use static address, then you must enter a static recipient address in the format, notify@etadirect.com.
Note: These drop-down lists display based on the selections made in the Recipient and Delivery Channel drop-down lists.
Customer Notification Time Select the time for notifying customers. For example, ETA, Service window, or Delivery window.
Reply Address Enter the e-mail address (for example, notify@etadirect.com) for sending notifications when you select Email as the Delivery channel and Customer, Dispatcher, or Resource as the Recipient.
Time Zone and Language Select the time zone and language for the email content when you select Email as the Delivery channel and use static address as the Recipient.
Static address Enter the email address or distribution group to which you want to send emails when you select Email as the Delivery channel and use static address as the Recipient.
Email address source Refers to the resource property that contains e-mail information when Dispatcher or Resource is selected as a recipient or refers to the user-defined property that contains e-mail information when Customer is selected as a recipient.
Notification time section
Sending time Select one of following options:
  • Day of event

  • Time of event

  • Day of route

For example, if you select Day of event, select +, and enter 2 in the Days field, then the messages are sent after two days from the Day of event.

from Select the starting time for the messages.

For example, if you select 8 AM from the drop-down list, then the messages are sent from 8 AM.

Available when either Day of event or Day of route is selected in the Sending time field.

Sending will time out in Specify the interval in hours and minutes. The messages are sent during the specified interval.
Number of Attempts On ‘failed’ status Indicates the maximum number of resend attempts. For example, if you enter 3 in the Interval field and 10 in the Minutes field, then the message is resent for 3 times after every 10 minutes.
Number of Attempts On ‘sent’ status

Available only for External Systems.

Indicates the maximum number of attempts to resend the notification status received.

For example, if you enter 3 in the Interval field and 10 in the Minutes field, then the notification status is resent for 3 times after every 10 minutes.

Sending delay Specify the time in minutes if you want some time to elapse after an event.
Block messages for specific days Select the days for which you don't want to send messages.
Block messages for holidays Select the option, if you don't want to send messages during holidays. You must set up holidays using Configuration, Holidays.
Blocked messages sending Indicates the number of days before the holiday. For example, if you select 2, then the messages are stopped before two days.

For our example, enter these details:

  1. Click Add New in the Scenario steps section.

    The Add scenario step dialog box displays.

  2. Enter Start test in the Name field.

  3. Select Start from the Type drop-down list.

  4. Select Email from the Delivery Channel drop-down list.

  5. Select day of event and + from the Sending time drop-down list.

  6. Enter 2 in the days field.

  7. Enter 5 in the hours field and 30 in the minutes field in the Sending will time out in field.

  8. Select Service Window from the Customer notification time drop-down list.

  9. Click Add.

    The Start test message step displays in the Scenario steps section. The Scenario steps section also displays other details such as sending time, the number of messages that are being sent today, and a graph of the progress. The graph and the queue details are hidden if the screen size is not enough to display the details.

Define the Message Content

The Patterns tab defines the content of the message that you want to send to your customers or systems. You can use variables within the body of the message to substitute the property value within the content of the message.

Based on the delivery channel, the template for the message differs as follows:
  • If the selected Delivery Channel is Email or External System, then the template for the message is defined using the Subject and Body fields.

  • If the selected Delivery Channel is Set Property, then the template for the message is defined using the property field and property value.

For example, assume that Cancellation Reason property is associated with the entity, Activity. When a customer cancels an activity, you need to set the Cancellation Reason property field for the activity to the value, 14. Using the Set Property delivery channel, you can use the Cancellation Reason property in the Subject field and define the required value in the Body field. So when the step is run, the application changes the value in the Cancellation Reason property to 14.

Also, you can determine when you want to generate the content of the message using the Generate content on message creation or Generate content on message sending options. Although the message is created when the message step is run, the property values may change after 40 minutes. Hence, select the Generate content on message sending option so that you receive the latest changes. For example, if you want to display the customer address in the content of the message, enter the label name of the property field using { }. For example, {caddress}.

  1. Select the Start test message step from the Scenario steps section.

  2. Select the Patterns tab.

  3. Enter test start in the Subject field.

  4. Enter start test activity started at {caddress} in the Body field.

  5. Select Generate content on message sending option and click Update.

Define Conditions

The Next Steps tab identifies the relation between different steps of a scenario and defines the conditions for the execution of subsequent steps.

For example, assume that the start step (that is, the start test activity) fails due to some reason and you want to inform a resource in the Helpdesk department that the activity has failed. To handle the above condition, you must create an inner step and define the message that you want to send to the Helpdesk department.
Note: By default, the Next Step drop-down list in the Start test, Next Steps tab is empty. Since the inner step handles a specific condition when the Start Step fails, it is required to create an inner step and link the Start step with the Inner step.
To create an inner step, follow the steps in the Define the settings for a scenario step using the Settings tab section, but modify these settings:
  • Enter test inner in the Name field, select Inner, Resource, and Email from the Type, Recipient, and Delivery Channel drop-down lists.

  • Enter the email address of the Helpdesk department in the Reply address field.

  • Select the Patterns tab and enter the message that you want to send in the Subject and Body fields.

For our example, let us configure the Start step so that when the Start step fails, the inner step (that is, test inner) runs and sends the failure message to the Helpdesk department.

  1. Select the Start test message step from the Scenario steps section.

  2. Select the Next Steps tab.

  3. Select Failed from the Status drop-down list.

  4. Select the check box and enter the required description.

  5. Select test inner from the Next Step drop-down list.

  6. Click Add.

    The configured condition displays in the list.

  7. Click Update.

    The test inner step is updated with the latest settings.

Block Message Steps

The Conditions tab enables you to define conditions to block the messages in a step. The application checks for any blocking conditions, and if the conditions are met, then the messages in the step are not processed.

Assume a scenario where you want to block the messages that are sent to the customer if the customer cancels an activity. To handle the above scenario, define a condition to verify whether the value in the Activity Status field is Cancelled as follows:
  1. Select the Start test message step from the Scenario steps section.

  2. Select the Conditions tab.

  3. Select Activity Status from the Field drop-down list.

  4. Select In from the Condition drop-down list.

  5. Enter Cancelled in the Value field.

  6. Select Failed from the Result drop-down list.

  7. Enter activity is cancelled in the Description field.

  8. Select Check on message sending option.

  9. Click Add.

    The configured condition displays in the list. If an activity is cancelled, then the customer receives a notification that is configured in the Conditions tab, that is, “failed, activity is cancelled.”

Add Launch Conditions

Launch conditions are trigger events that invoke message scenarios and scenario steps to deliver configured messages to client systems.

Assume that you want to invoke the message scenario that you have created, that is, Route Not Activated when a resource’s route is not activated. Therefore, you need to add a launch condition to invoke the scenario as follows:
  1. Click Configuration > Message Scenarios.

  2. Click Add New in the Launch Conditions section.

  3. Select Route is not Activated from the The scenario will be launched when drop-down list.

  4. Enter the number of minutes in the minutes after shift starts according to calendar field.

  5. Click OK.

    The launch condition displays in the Launch Conditions section of the Message Scenarios page. For each launch condition of the scenario, the Launch Conditions section also displays the number of messages that are in the queue. If the number of messages is greater than 999, then the numbers are displayed as follows:
    • Range 1000-999999 - "k". For example, 1000 messages are displayed as "1k"; 10000 messages are displayed as "10k".

    • Range 1000000 and greater - "m". For example, 1000000 messages are displayed as "1m"; 123000000 messages are displayed as "123m"

    Note: When the user selects a message scenario in the routing plan as a Fallback option, a read-only launch condition, Routing fallback is automatically populated in the message scenario. When the user removes the message scenarios from all associated routing plans, the launch condition is removed from the message scenario. The launch condition has a count of routing plans to which it is associated. You can click the count of routing plans in the launch condition UI to view the routing plans.

Send Notification Messages

Channels define a mechanism to communicate notification triggers to external systems. The Email agent is used for sending messages when the Email delivery channel is selected.

However, if you want to send messages to an external system (for example, client system), then you must define the details of the client system (such as Host, Port number, URL, Connection method, and so on) using the Delivery Channels page. For example, let us create a delivery channel, external sys 1 as follows:
  1. Click Channels.

    The Delivery Channels page displays.
  2. Click the Plus icon on the left pane.

  3. Enter external sys 1 in the Name field.

  4. Select the required option from the Status drop-down list.

    Note: If notification scenarios contain at least one message step that uses an internal delivery channel (e-mail or voice) then that channel is accessible in the list of channels. A user with appropriate permissions can select Active or Inactive to resume or stop the message delivery for any external or internal channel. For example, you can block a channel using the Inactive option in Test instances to disallow test messages to reach real customers. Messages that are not delivered due to inactivated delivery channel get the status 'obsolete' with the description, EXTERNAL_NOTIFICATION_ARE_DISABLED. Note that the 'set property' messages don't have a delivery channel and cannot be handled this way.
  5. Enter agent.com in the Host field and 8080 in the Port number field.

    Note: Enter one of these values (20, 21, 22, 25, 80, 290, 389, 443, 587, 873, 2401, 3668, 4011, 4142, 5308, 5666, 5900, 5901, 6666, 6460, 7800, 8080 8443, 14861 and 20106) in the Port field.
  6. Enter the URL Path of the server (optional).

  7. Enter the name and password of the user for authorization purpose.

  8. Select the Allow basic access authentication check box if you want to implement HTTP basic authentication while integrating with external systems.

    When you select the check box, the outbound methods (such as send_message, drop_message, get_message_status methods) send the standard HTTP header "Authorization" with base64-encoded user credentials (standard basic access authentication). Also, the <user> SOAP structure is sent in the body of the request. The client application can either use the standard HTTP header "Authorization" or the <user> SOAP structure to send user credentials in the request.
    Note: When the check box is not selected, the standard HTTP header is not used in the request and the client application can use the <user> SOAP structure for authentication. For more information, see the Integrating with Outbound API Guide.
  9. Select a connection from the Connection drop-down list to denote the encryption protocol type.

    Note: By default, Not Encrypted option is selected. If you select default encryption or any other encryption type, then complete the necessary fields in the Advanced Settings section.
  10. Click Add.

    The channel displays in the Delivery Channel drop-down list in the Add scenario step and Modify scenario step dialog boxes. The delivery channel, external sys 1 also displays on the left pane on the Delivery Channels page. The channel details are displayed in:
    • Green if there are no warnings and the channel is active

    • Gray if there are no warnings and channel is inactive

    • Red if there are warnings, or count of message scenarios is greater than 0 and the channel is inactive

    Active and Inactive are also displayed on active and inactive channels respectively.

Use Collaboration as a Delivery Channel

You can use collaboration as a delivery channel to send alerts of different types of events or situations in Oracle Field Service to collaboration users (for example, technicians, help desk operators, and resources). Also, you can broadcast notifications or alerts to collaboration user groups or help desk groups on occurrence of an event or when a predefined condition is met in Oracle Field Service.

  • Subscribe to Collaboration to view the Collaboration option as a delivery channel in the message scenario. View the About page in your instance to verify whether the service is enabled.

  • Create collaboration users, user groups, or help desk groups.
    Note: For more information on configuration settings, see the Configuring Collaboration section in the Oracle Field Service Collaboration Service Guide.

For example, assume that you want to notify the resource using collaboration as a delivery channel when a activity is created in Oracle Field Service. Assume that the message scenario, new appt is associated with the Activity is Created launch condition and has a scenario step, Collab Alert.

  1. Log in to Oracle Field Service as a Administrator.

  2. Click Configuration, Message Scenarios.

  3. Select the Collab Alert scenario step.

  4. Select Collaboration from the Delivery Channel drop-down list in the Settings tab.

  5. Select one of these options from the Recipient drop-down list:

    • Resource: Delivers message to the resource associated with the launch condition. By default, Oracle Field Service considers the language and time zone of the user associated with the resource. If the collaboration permission is not configured for the resource, then the message scenario displays a False Method status in the Messages tab of the Activity Details page for the scenario step.
    • use static address: Enables you to send the message to specific users, user groups, and helpdesks. Click Add New and search for the required users, user groups, and helpdesks. Select the required users, user groups, and helpdesks to add them to the Recipients section. You must enter at least three letters in the Search field to search for the required users, user groups, and helpdesks.
  6. Enter the message content in the Subject and Body fields of the Patterns tab.

    The default language of the company is configured from the My Display, Language drop-down list and is selected as the language for the message content. To add more languages, see Configure the Display Page. For example, if English is configured as the default language and if the Subject and Body fields in the Patterns tab are populated is English, then regardless of the user’s language, the message is sent to the recipient in English.

    However, you can use the Pattern tab to specify another language for the message content. You can specify any one of the languages selected from the My Display setting as the language for the message content. For example, if English is configured as the default language and the Subject and Body fields in the Patterns tab is populated is Spanish, then the message is sent to the recipient user in Spanish. However, be aware that the placeholders are not translated; they are always in English. For example if there is a placeholder {activity_status}, it will not be translated; it will be in English.

    If the default language is not configured then English is considered as the default language of the recipient and the message is sent to the recipient in English.

  7. Configure the required fields and click Save.

    The details such as sending time and the selected delivery channel are updated for the Scenario step.
Assume that a new activity is assigned to the resource, Phillip. The message scenario is triggered and the Collab Alert scenario step is displayed with the New status in the Messages tab of the Activity Details page.
When the message alert is sent to the resource, the status in the Messages tab of the Activity Details page changes to Sent.
Note: If the scenario step is not configured properly or if the message alert is not sent to the resource, the status in the Messages tab of the Activity Details page changes to Failed. However, if a message is invalidated because of an activity-related operation in Oracle Field Service (such as delete, move, suspend activity), the status in the Messages tab of the Activity Details page changes to Obsolete.
To view the message alert, log in to Oracle Field Service using resource’s login credentials.

For more information, see the About Collaboration Window section in the Oracle Field Service Collaboration Service Guide.

Properties

Each entity (for example, activity, resource, inventory, and users) contains a set of associated attributes. For example, resource records may contain attributes such as name and contact information as well as physical attributes such as gender or a photograph. These attributes within Oracle Field Service are combinations of fields or custom properties.

Properties with the Type “Field” are the native system properties that are available for the specified entities. For example, Name (property label, cname) is associated with an Activity, and Serial Number (property label, invsn) is associated with Inventory. Field type of properties can be mapped with similar client properties.
Note:
  • Multiple fields or properties with the same name can exist. For example, Name can refer to a customer’s name (property label, cname) or a resource’s name (property label, pname). In this example, each Name property is assigned to a different entity and has a different property label.
  • When custom property values exceed 255 bytes, the entire value is shown in the activity details, API responses, and Outbound Messages. However, only the first 255 bytes are used for search, visibility conditions, activity inventory list columns and their sorting, travel, activity duration, visit, and Work Zone Keys. If you create a condition with long values, only the first 255 bytes are used with historic data; all the long values that are added after you create the new condition will use the full set of data.
Custom properties are attributes of entities that are unique to each client. You can create them through the user interface, import them, or create through an API. Once added, these properties are available for use in page configurations, filters, and numerous configuration areas (for example, search fields, duration field, and so on). You can create these types of properties:
  • String: These are custom properties that require alphanumeric entries. These can include free text boxes, URLs, phone numbers, or email addresses.

  • Integer: These are custom properties that require numeric entries. This option can also be used for check boxes.

  • Enumeration: These are custom properties that require selections from fixed lists. Option buttons and combo (drop-down lists) boxes are common examples of this property type.

  • File: These are custom properties that require some type of file upload. These could include MIME types such as .gif, .jpg, .pdf, .mpeg, .zip, html, .wav, or .doc. Examples of File properties could be customer signatures or even technician photos.

Create a String Property

The string property includes free text boxes, URLs, phone numbers, and email addresses. Assume that resources must enter remarks for an activity after the activity is closed. The Activity Details form must contain a text box, so the resource can enter the remarks. The text box that you add here, is a string property.

  1. Click Configuration.

  2. Click Properties in the Resources, Activities, Inventories section.

  3. Click Add New.

  4. Select String from theProperty Type drop-down list.

  5. Complete these fields:

    • Property name(mandatory): Enter a name that you want to display to the end user in English and in all the languages that are active in the application.

    • Property label(mandatory): Enter a Unique database identifier for the Oracle Field Service API.

    • Property hint(optional): Enter a hint that you want to display when a user hovers over the field name. For example, Enter comments if any. Enter the text in English and in all the languages that are active in the application.

    • Regular expression: Enter an expression to validate the values or format the values in a certain way.

    • Entity(mandatory): Select Activity since the property is associated with the Activity Details form.

    • Lines Count(mandatory): Enter the number of lines that you want the property to display in the Activity Details form. For example, enter 3 to display a maximum of three lines.

    • GUI (optional): Select one of these options to define how the property displays to users:

      • Text Element: Displays as a free text field. For our example, select this option.

      • URL: Displays as a clickable URL.

      • Phone: Displays as a clickable phone number.

      • Email: Displays as a clickable email address.

      • Geolocation Element: Displays a button to show the location on a map.

    • Regular expression (optional): Enter an expression to validate input or to force the data to display in a certain way.

      For example, if you want to display $23,540, then use this regular expression: /^/$?([1-9]{1}[0-9]{0,2}(/,[0-9]{3})*(/.[0-9]{0,2})?|[1-9]{1}[0-9]{0,}(/.[0-9]{0,2})?|0(/.[0-9]{0,2})?|(/.[0-9]{1,2})?)$/

      Other examples:
      • Ethernet ARP address: /^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$/

      • Phone number: (555)5555555: /[/(/)\d/-]{10}/

      • 16-bit integer: (0-65535): /(^\d{0,4}$)|(^6553[0-5]$)|(^655[0-2][0-9]$)|(^65[0-4]\d{2}$)|(^6[0-4]\d{3}$)|(^[0-5]\d{4}$)/

      • 1 digit: (0-9): /^\d{1}$/

      • 2 digits: (01-99): /^\d{2}$/

      • Integer: (0-99): /^\d{1,2}$/

      • Integer: (0-999): /^\d{1,3}$/

      • Any 6 symbols(you can change 6 to any number): /^.{6}$/u

      • Currency (USD with 2 decimal places): /^/$?([1-9]{1}[0-9]{0,2}(/,[0-9]{3})*(/.[0-9]{0,2})?|[1-9]{1}[0-9]{0,}(/.[0-9]{0,2})?|0(/.[0-9]{0,2})?|(/.[0-9]{1,2})?)$/

      • Date formatted as DD-MM-YYYY: /^((0[1-9])|([1-2][0-9])|30|31)-((0[1-9])|1[0-2])-2[0-9]{3}$/

    • Clone property on Reopen/Prework (optional): Enables you to duplicate the property while reopening the activity or applying prework for a new activity.

    • Formatting (optional): If selected, displays these options:

      • Regular expression

      • XSL transformation (converts an XML file into a table format viewable in HTML that is read-only).
        Note: Formatted properties are not available for presentation on the Inventory Grid context layout structure.

      Assume that you want to display this data from a client system within Oracle Field Service:

      Group Price
      One Time Charges and Credits $ 100.00
      Programming Change $ 5.00
      Programming Change $ 5.00
      Programming Change $ 5.00
      Programming Change $ 5.00
      UNKNOWN $ 0.00
      Monthly Charges $ 129.98
      America’s Top 250 $ 69.99
      HD/SD (2TV) Receiver $ 14.00
      HD/SD (2TV) Receiver $ 14.00
      DVR Service $ 6.00
      Protection Plan $ 6.00
      Israeli: The Israeli Network $ 19.99
      Monthly Credits $ -10.00
      Cr: Agent $ 10x24 Mo $ -10.00
      Monthly Charges and Credits $ 119.98

    Use this regular expression for the above data: /(/s+)?(.+/w)/s+(/$)/s+(.*)/n?/im = [item group="$1"] [name]$2[/name][price]$4[/price][currency]$3[/currency][/item]

    This XML file converts the data given earlier into a table format:

    [xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"]
    [xsl:template match="/"]
    	
    	[style]
    		.property_table
    		{
    			font-size:12px;
    			font-family: Arial;
    			border-collapse: collapse;
    		}
    		.property_table .property_name
    		{
    			padding-left:15px;
    		}
    		.property_table td
    		{
    			border: 1px solid grey;
    			padding: 4px;
    		}
    		.property_table .property_price
    		{
    			text-aligh:right;
    		}
    		.property_group
    		{
    			background-color:#ccc;
    			font-weight: bold;
    		}
    		.property_group .property_name
    		{
    			padding-left:5px;
    			font-weight: bold;
    		}
    	[/style]
    	[table class="property_table"]
    		[xsl:for-each select="root/item"]
    			[xsl:choose]
    				[xsl:when test="@group=' '"]
    					[tr class="property_group"]
    						[td class="property_name"] [xsl:value-of select="name"/] [/td]
    						[td class="property_price"]
    							[span] [xsl:value-of select="currency"/] [/span]
    							[xsl:value-of select="price"/]
    						[/td]
    					[/tr]
    				[/xsl:when]
    				[xsl:otherwise]	
    					[tr] 
    						[td class="property_name"] [xsl:value-of select="name"/] [/td]
    						[td class="property_price"]
    							[span] [xsl:value-of select="currency"/] [/span]
    							[xsl:value-of select="price"/]
    						[/td]
    					[/tr]
    				[/xsl:otherwise]	
    			[/xsl:choose]
    		[/xsl:for-each]
    	[/table]
    [/xsl:template]
    [/xsl:stylesheet]

    Using XSL transformation, the above XML file is displayed in HTML as shown in this screenshot:

    This screenshot shows the sample data displayed in HTML.
  6. Click Add.

    A system generated ID is assigned to the property. You can perform these actions:
    • Click Export to export the properties to an XML file.

    • Click Import, Browse, and select the XML file that you want to import.

Add a String Property to the Screen Configuration

After you create a property, you can assign it to a specific user type and determine where the property type displays on the page.

You can define these visibility settings for the property type:
  • Read only, read/write, or mandatory options.

  • Conditions under which the property type displays.

    Note: Not all conditions are available for every page context.

Let’s assign the CSR Notes string property to the Administrator User Type, and add it to the Activity Details page. Also, let us set the property type to Read-Only when the activity status is Completed and change the property type to Read Write when the activity status is Pending. To add a string property:

  1. Click Configuration, User Types in the Users and Security section.

    The existing users display in the left pane.
  2. Select Administrator from the left pane.

  3. Select the Screen Configuration tab.

  4. Expand Manage and click Add activity/Activity details.

  5. Select a property from the Layout Structure pane and click Add property.

  6. Select the property, CSR Notes and click OK.

    The CSR Notes property displays in the Layout Structure pane.
  7. Click Add New Visibility and select Read-Only.

  8. Click Add New Condition.

  9. Select Activity Status and in (equal) from the drop-down lists.

  10. Click the Plus icon, select Completed, and clickSave.

  11. Click Add New Visibility and selectRead-Write.

  12. Click Add New Condition.

  13. Select Activity Status and in (equal) from the drop-down lists.

  14. Click the Plus icon, select Pending, and click Save.

You can view both the conditions in the Conditions column.

Create an Enumeration Property

Option buttons and drop-down lists are examples of the enumeration property. This means, you can have a set of valid values and you can select only one value from the set. For example, you have four types of customers, Standard, Gold, Silver, and Bronze and you want to indicate the customer type on each activity record.

This example creates an enumeration property, Customer level with four values, Standard, Gold, Silver, and Bronze, and displays the property as a drop-down list in the user interface.
  1. Click Properties in the Resources, Activities, Inventories section.

  2. Click Add New.

  3. Select Enumeration from the Property Type drop-down list.

  4. Enter Customer level in the Property Name field. Enter the name in English and in all the languages that are active in the application.

  5. Enter Cust_level in the Property label field.

  6. Select Activity from the Entity drop-down list.

  7. Select Combobox from the GUI drop-down list.

  8. Specify the value, Standard in the Enumeration Values field and click Add.

    Note: The values display in alpha-numeric order. The system automatically applies an index value to each specified value, and the index value is case sensitive. The APIs reference the index value. For example, if you want to use a readable value for the value, customer not home, you can use the code CNH instead of the default index value, 1 and map the code to the client system. You cannot edit the index value, after it is added.
  9. Repeat step 6 for each value, that is, Gold, Silver, and Bronze.

    The specified values display in the Values field.

  10. Select a value from the Values field.

  11. Clear the Active check box.

  12. Click Edit to make a value inactive and does not display in the user interface.

  13. Click Add.

Create a File Property

The File property type supports transferring of files such as documents, photos, or signatures. This means, you can upload MIME types such as .gif, .jpg, .pdf, .mpeg, .zip, html, .wav, or .doc files for activities.

  1. Click Configuration > Properties.

  2. Click Add New.

  3. Select File from the Property Type drop-down list.

  4. Enter a name for the property in the Property Name field. Enter the name in English and in all the languages that are active in the application.

    This is the name that is displayed on the context layout structure and any page to which the property is added.
  5. Enter a label for the property in the Property label field.

  6. Enter a hint that you want to display when a user hovers over the field name in the Property hint field. Enter the hint in English and in all the languages that are active in the application.

  7. Select the entity to which the property belongs, in the Entity field.

  8. Select one of these options for the GUI field:

    Option Description
    File element Select this option to upload a file. When uploaded, the file displays as a text link in the user interface. These fields are displayed:
    • File size limit: Select the maximum file size you want to allow for File elements in Oracle Field Service Mobile for Android and iOS and Oracle Field Service Core Application. This field is displayed only for the File element option. The default and the maximum size allowed is 5 MB. This limitation does not apply to the APIs.

    • Allowed MIME types delimiter: Select whether you want to display separate allowed MIME types with commas, or you want to display each allowed MIME type on a new line.

    • Allowed MIME Types: Click the required types of files you want to allow for upload.

    Signature element Select this option to capture the resource’s signature.
    Image element Select this option to enable the user’s device to capture and upload the user’s photo, and to display the image as a thumbnail. These fields are displayed:
    • Allow draw on image: Select this check box to let the user draw on the captured image using a stylus.

    • Get geolocation: Select this option to save the location information on a map with the captured image.

    • Maximum picture width (in pixels): Enter the maximum width the captured image can have. The recommended width is 1000 pixels.

    • Maximum picture height (in pixels): Enter the maximum height the captured image can have. The recommended height is 1000 pixels. Maximum resolution limits should be exceed 5000x5000 pixels. The Minimal value is 10 pixels.

  9. Select whether you want to copy the property data when an activity is reopened or has a pre-work activity in the Clone property data on Reopen or Prework field.

  10. Click Add.

    The new property type is added. Add this property to the context layout of the page for the user profile for which you want to display.

Supported MIME Types

The full list of supported MIME-types and the matching file extensions is provided here.

MIME Type Supported File Extensions
animation/narrative 'nml'
application/mspowerpoint 'pot', 'pps', 'ppt', 'ppz'
application/msword 'doc', 'dot'
application/oda 'oda'
application/onenote 'one', 'onetoc2', 'onetmp', 'onepkg'
application/pdf 'pdf'
application/rtf 'rtf'
application/vnd.ms-excel 'xls', 'xlt', 'xla'
application/vnd.ms-excel.addin.macroEnabled.12 'xlam'
application/vnd.ms-excel.sheet.binary.macroEnabled.12 'xlsb'
application/vnd.ms-excel.sheet.macroEnabled.12 'xlsm'
application/vnd.ms-excel.template.macroEnabled.12 'xltm'
application/vnd.ms-officetheme 'thmx'
application/vnd.ms-powerpoint.addin.macroEnabled.12 'ppam'
application/vnd.ms-powerpoint.presentation.macroEnabled.12 'pptm'
application/vnd.ms-powerpoint.slide.macroEnabled.12 'sldm'
application/vnd.ms-powerpoint.slideshow.macroEnabled.12 'ppsm'
application/vnd.ms-powerpoint.template.macroEnabled.12 'potm'
application/vnd.ms-word.document.macroEnabled.12 'docm'
application/vnd.ms-word.template.macroEnabled.12 'dotm'
application/vnd.openxmlformats-officedocument.presentationml.presentation 'pptx'
application/vnd.openxmlformats-officedocument.presentationml.slide ' 'sldx'
application/vnd.openxmlformats-officedocument.presentationml.slideshow 'ppsx'
application/vnd.openxmlformats-officedocument.presentationml.template 'potx'
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 'xlsx'
application/vnd.openxmlformats-officedocument.spreadsheetml.template 'xltx'
application/vnd.openxmlformats-officedocument.wordprocessingml.document 'docx'
application/vnd.openxmlformats-officedocument.wordprocessingml.template 'dotx’
application/x-excel 'xls'
application/x-gtar 'gtar'
application/x-gzip 'gz'
application/x-pointplus 'css'
application/x-shockwave-flash 'swf'
application/x-sprite 'spr', 'sprite'
application/x-tar 'tar', 'tgz'
application/zip 'zip'
audio/mpeg 'mp2', 'mp3', 'mpga'
audio/x-wav 'wav'
chemical/x-pdb 'pdb'
image/gif 'gif'
image/jpeg 'jpe', 'jpeg', 'jpg'
image/png 'png'
image/tiff 'tif', 'tiff'
image/x-ico 'ico'
text/html 'htm', 'html'
text/plain 'txt'
text/richtext 'rtx'
text/tab-separated-values 'tsv'
text/x-speech 'talk'
text/x-vcard 'vcf'
video/mp4 'mp4'
video/mpeg 'mpe', 'mpeg', 'mpg'
video/quicktime 'mov', 'qt'
video/x-msvideo 'avi'

Create an Integer Property

Check boxes and text fields are examples of the integer property. Use the integer property to enter numerical values such as port number, or to select your decision such as whether an additional inventory has been approved by the dispatcher [Yes/No].

This example creates an integer property, Customer confirmed, and displays the property as a check box in the user interface.
  1. Navigate to the Configuration page.

  2. Click Properties in the Resources, Activities, Inventories section.

  3. Click Add New.

  4. Select Integer from the Property Type drop-down list.

  5. Enter Customer confirmed in the Property Name field. Enter the name in English and in all the languages that are active in the application.

  6. Enter Cust_decision in the Property label field.

  7. Select Activity from the Entity drop-down list.

  8. Select Checkbox element for GUI.

  9. Enter an expression in the Regular expression field to validate input or to force the data to display in a certain way.

  10. Select whether you want to duplicate the property while reopening the activity or applying pre-work for a new activity.

  11. Click Add.

    The newly added property appears on the Properties page.

Resource Types

A resource type helps you identify these differences:

  • Account for cost differences between full time employees and contractors.

  • Identify the resources that you want to track using geolocation.

  • Manage quota and capacity for resources.

  • Distinguish between team holder and team member.

  • Share a resource’s inventory and work skills in a team.

You can create different resource types to differentiate the hierarchy of the Resource Tree. While creating a resource type, each resource type is assigned to a role. The roles (Field Resource, Vehicle, Tool, Bucket, and Organization Unit) enable you to differentiate the hierarchy of the Resource Tree. Each role is represented with the icons, Blue, Yellow, or Grey.

By default, the Load Threshold section displays (unless the Organization Unit role is selected) on the Add Resource Type dialog box and has the following options to determine how the icons display on the resource tree based on the resource’s load (full, normal, or empty load):
  • Number of Activities: Defined amount of activities, over which a resource is considered to have full load and below which is considered an empty load.

  • Hours: Defined amount of hours including travel, over which a resource is considered to have full load and below which is considered an empty load.

  • Time Percent: Defined % of a resource’s work schedule for the day that includes activities and travels among them that is considered to be full, normal or empty. Travel time to and from work for the day is not included in these calculations.

Note: Specify the number of activities, hours, percentages in the Full Load or Empty fields. The display of icons on the resource tree depends on the specified values. For example, if 10 activities represent Full load, then the Blue icon displays.

Add a Resource Type for the Field Resource Role

A Field Resource is a resource that performs work, has work skills and work zones associated, and has a related user (actual person performing work or group of people). A Field Resource requires a user, can execute work, is shown with a Tech icon, and does not include the Organization unit option.

Assume that you want to assign activities to a technician. You have to first create the resource type, Technician and then select Field Resource from the Role drop-down list.
Note: Some features are available only during the initial configuration. This will vary based on the options selected during the configuration. Features that are not available for editing after the initial configuration will be greyed out.
To add a resource type for the Field Resource role:
  1. Click Company Name > Configuration.

  2. Click Resource Types in the Resources, Activities, Inventories section.

  3. Click Add resource type.

  4. Complete these fields:

    Field Description
    Name (mandatory) Enter a name for the resource type. All supported languages are listed.
    Label (mandatory) A unique identifier for the resource type that is mapped to the Resource Management API.
    Active By default, the Active check box is selected and the resource type is activated.
    Statistic Parameters section
    Personalize the estimation of activity duration check box When selected, the resource’s personal profile is used for duration calculations. Else, uses only company estimates. For more information, see How Activity Duration Is Calculated
    Use durations reported to enhance company-wide estimations check box When selected, company-wide estimations are modified based on the data reported by the resource. If not selected, the company-wide estimations are not changed. This applies to both activity durations and travel estimations. don't select this check box, if you don't want the durations reported by the resource to affect company level estimations.
    Do not consider reported data for the first ____ working days, for statistic estimations Data reported by the resource does not affect the company-wide estimations for the initial number of days specified in this field. The date is considered from the time the user accesses the system. Default value is 5 days. For example, if you enter 15 days, then the data reported by the resource for activity and travel durations are ignored for the first 15 days and will not be considered while calculating the company-wide estimates. This field is enabled only if the Use data reported to enhance company-wide estimations field is selected.
  5. Select Field Resource from the Role drop-down list.

  6. Select the required features from this list:

    • Resource can participate in a team: Select the Resource can participate in a team check box to determine whether the resource type is an assistant for teamwork activities. If deselected, then you cannot add the resource type, technician as an assistant to a team.

    • Resource can be a teamholder: Select the Resource can be a teamholder check box to determine whether the resource type is a primary team holder of an activity.
      Note: An activity that requires a team is always assigned to the team holder whereas the assisting teamwork activities are assigned to the assistants for the duration of the teamwork.
    • Share inventory in teamwork: Determines whether the resource type shares inventory with other team members after an activity is started. For example, if the team holder’s inventory has 5 items and the assistant’s inventory has 3 items, then when the activity is started, there are 8 items available for use at the job site.

    • Share geolocation in teamwork: Select the check box to define whether a resource (team holder or assistant) shares the geolocation in a teamwork assignment. Although, the application uses the GPS device of each resource to predict the location of the resource, these situations can occur:
      • Application is unable to obtain coordinates since the device of a resource has stopped to work.

      • Application is unable to find the location of the resource due to some reasons.

      In the above situations, the application uses an algorithm to predict the location of the resource using the coordinates of other resources in the team. Therefore, you can view the location of each team resource in the map view.

    • Share work skills in teamwork (team-member only): Enables the resource to share work skills with the team holder. Sharing is defined on the work skill level according to the "Sharing of the skill in the team" parameter configured in the Add work skill dialog box.

    • Used for Quota management: Enables you to consider the working time of each resource into the overall workflow capacity calculation of the bucket.

      For example, assume that each resource (Technician 1, Technician 2, and Technician 3 configured as a Field Resource) has a capacity of 480 minutes per day and the Use as Capacity Area check box is selected for each resource. Therefore, the Max Available field in the bucket has the overall workflow capacity of 1440 minutes. Now, if a new resource type, Technician 4 is added and if the Use as Capacity Area check box is selected, then the overall workflow capacity of the bucket changes to 1920 minutes.

    • Routing can assign activities: Select the check box if you want routing to assign activities to a resource.

      If selected, these options enable you to specify the cost of the resource’s time that helps you to differentiate between resources (for example, Full time resources versus Contractors):

      • Working hours cost: Actual working hours of the resource during the day based on activity durations. Select an option (Low, Normal, High, Highest). The routing algorithm factors working time cost differences between resource types for assignments.

      • Overtime cost: Overtime refers to the minutes worked beyond the end of the resource’s working hours for the day. Specify cost increases either as X minutes after the end of the shift or the time beyond the X minutes threshold.

      • Travel Time cost: Refers to the estimated time and the cost required for travelling between activities.

    • Working time : Define the travel allowance for resources using these options:
      • Start travel: Enables routing to consider travel time from the beginning of the resource’s working time for the day and to the resource’s first activity. The application estimates the actual travel time to the location of the first activity, when a resource’s Start location is defined. Note that when a route includes activities that require travel and activities that don't need travel, the travel between activities is split into two (or more) pieces by inserting non-travel activities in between. If there is any idle time before an activity, it is considered as travel time for the next activity. Select one of these options:
        • Travel time to the first activity is not included from the Working Time Start – when selected, travel time to the first activity will be calculated before the Working Time Start value. If an activity has a Service Window of 8:00 am-10:00 am, the activity will have an ETA of 8:00 am and the resource will have to leave their start location to arrive by 8:00 am.

        • Travel time to the first activity is included from the Working Time Start – when selected, travel time will be calculated to the first activity. If a resource has 30 minutes of travel and the activity has a service window of 8:00 am-10:00 am the activity’s ETA will be 08:30 am.

        • Resource is allotted up to <number> minutes of travel time prior to the Working Time Start – when selected, a portion of the travel time can occur prior to the start of the shift. If the value is set to 30 minutes and the resource need 45 minutes of travel the first 30 minutes will occur prior to the start of the shift and the ETA activity’s ETA will be 08:15 am.

      • Final travel: Enables routing to consider travel time to a known end location. Select one of these options:
        • Travel time from the last activity to the Resources End Location is not included from the Working Time End – when selected, travel time to the final location will be calculated after the Working Time End value. If a resource’s shift ends at 6:00 pm with no overtime allowed, routing can assign activities that can end at 6:00 pm.

        • Travel time from the last activity to the Resources End Location is included from the Working Time End – when selected, travel time to the final location will be calculated. If a resource’s shift ends at 6:00 pm with no overtime allowed, routing cannot assign activities that can end at 6:00 pm.

        • Resource is allotted up to <number> minutes of travel time after the Working Time End – when selected, a portion of the travel time will occur after the shift ends. Suppose that the resource’s shift ends at 6:00 pm with no overtime allowed. When the value is set to 30 minutes and the resource needs 45 minutes of travel to the end location, the latest an activity can end would be 5:45pm.

    • Enable 'Not activated in time' alert and trigger: Represents an alert that the resource’s route is not activated. For example, consider the resources, Technician 1 and Technician 2 configured as field resources. If the Enable 'Not activated in time' alert and trigger check box is selected for the resource, Technician 1 and not selected for Technician 2, then the notification messages are created only for Technician 1.

  7. Click Add.

    Note: These features are available when a role, Vehicle or Tool is assigned to a resource type:
    • Share inventory in teamwork

    • Share geolocation in teamwork

    • Share work skills in teamwork (team-member only)

    • Working time includes travel to first activity

    • Working time includes travel from last activity

    • Enable 'Not activated in time' alert and trigger

The resource type, technician displays on the Resource Types page. If you click Modify and change a feature setting of a resource type, the application automatically applies the changes to the resource type.

Example of a Travel Allowance Calculation

Roger’s assigned Resource Type has these Work Time configurations:
  • Travel time to the first activity is included from the Working Time Start

  • Travel time from the last activity to the Resources End Location is included from the Working Time End

Jane and John’s assigned Resource Type has these Working Time configurations:
  • Resource is allotted up to 30 minutes of travel time prior to the Working Time Start

  • Resource is allotted up to 30 minutes of travel time after the Working Time End

Consider Roger, Jane, and John, who have their work shift from 9:00 am to 6:00 pm and these distances from work place:
  • Roger lives 30 minutes from his first and last job. So, for both jobs, 30 minutes of travel is included part of his workday.

  • Jane lives 45 minutes away from the first and last job. So, for both of her jobs only 15 minutes of the travel should be counted as part of her workday and the additional 30 minutes is beyond her workday.

  • John lives 20 minutes away from his first and last job. So, no travel is part of his workday and the 20 minutes travel for the last job is done beyond his workday.

Using this example, if a new activity is created that is estimated to finish by 5:45 pm and overtime is no allowed, routing will not assign this activity to Roger. If it was assigned, Roger would incur overtime, because his shift ends at 6:00 pm. The routing engine would look for a more suitable resource.

Add a Resource Type for the Bucket Role

A bucket accumulates the work that has not yet been distributed to field resources. A bucket does not require a user, cannot execute work or activities, is shown with a Double Tech icon, includes the group option, and can have activities assigned.

Note: Some features are available only during the initial configuration. This will vary based on the options selected during the configuration. Features that are not available for editing after the initial configuration will be greyed out.
  1. Click Configuration.

  2. Click Resource Types in the Resources, Activities, Inventories section.

  3. Click Add resource type.

  4. Select Bucket from the Role drop-down list.

  5. Complete these fields:

    • Name (Mandatory): Enter a name for the resource type. All supported languages are listed.

    • Label (Mandatory): A unique identifier for the resource type that is mapped to the Resource Management API.

    • Active: Select the Active check box to activate the resource type.

  6. Select the Use as Capacity Area check box.

    This option is available only if you have purchased Capacity Cloud Service. For more details about Quota Management in Bucket, see the Oracle Field Service Using Capacity Cloud Service Guide guide.
  7. Select the Routing can assign activities check box if you want routing to assign activities to the bucket.

  8. Click Add.

    The Bucket resource type displays on the Resource Types page.

Add a Resource Type for the Organization Unit Role

An organization unit aggregates field resources, vehicles, and tools in a hierarchical structure to simplify management and reporting. An organization unit does not require a user, cannot execute work or activities, is shown with a Double Tech icon, includes the group option, and can have activities assigned.

Note: Some features are available only during the initial configuration. This will vary based on the options selected during the configuration. Features that are not available for editing after the initial configuration will be greyed out.
  1. Click Company Name > Configuration.

  2. Click Resource Types in the Resources, Activities, Inventories section.

  3. Click Add resource type.

  4. Select Organization unit from the Role drop-down list.

  5. Complete these fields:

    • Name (Mandatory): Enter a name for the resource type. All supported languages are listed.

    • Label (Mandatory): A unique identifier for the resource type that is mapped to the Resource Management API.

    • Active: Select the Active check box to activate the resource type.

  6. Select the Use as Capacity Area check box to aggregate the capacity across buckets.

    For example, assume that the maximum available capacity for Bucket 1 is 1920 minutes and the Use as Capacity Area check box is selected. Bucket 2 has a maximum available capacity of 2400 minutes and the Use as Capacity Area check box is not selected. Now, if you select the Use as Capacity Area check box for Bucket 2, then the Group resource type aggregates the capacity across Bucket 1 and Bucket 2 and changes the maximum available capacity of the Group to 4320 minutes.
  7. Click Add.

The Organization Unit resource type displays on the Resource Types page.

Add a Resource Type for Contingent Worker

Contingent (or Infrequent) Workforce is one where the workers don't work directly for the company. They are contractors that may not have dedicated or assigned routes everyday. They will be assigned work infrequently on an ad-hoc basis.

Note: You must have selected the Contingent Worker service and it must be available as part of your Oracle Field Service subscription.
  1. Click Configuration.

  2. Click Resource Types in the Resources, Activities, Inventories section.

  3. Click Add resource type.

  4. Complete these fields:

    Field Description
    Name (mandatory) Enter a name for the resource type. All supported languages are listed.
    Label (mandatory) A unique identifier for the resource type that is mapped to the Resource Management API.
    Active By default, the Active check box is selected and the resource type is activated.
  5. Select Field Resource from the Role drop-down list.

  6. Select the Resource is a contingent worker check box.

    The remaining check boxes are grayed out. These rules apply to contingent worker resources:
    • When the Resource is a contingent worker check box is selected, the Role cannot be anything other than "Field Resource".

    • This resource cannot participate in teamwork.

    • This resource cannot access resources other than themselves.

    • This resource cannot access the video chat service if provisioned.

    • Quota does not consider contingent workers while calculating the available capacity.

    • Bulk, urgent, and immediate routing don't assign activities to this resource.

    • The alert regarding route activation does not display for this resource.

    • Travel and activity duration from these resources are not included in the company-wide statistics.

    Note: The Resource is a contingent worker check box is grayed out on the Edit resource type dialog box. This means, after you create a contingent worker resource type, you cannot change it back to a normal resource. Further, a contingent worker resource can only be a field resource and this resource must have only one corresponding contingent worker user. Contingent workers are automatically removed from the application, if they have not activated a route in 12 continuous months.

Shifts

Shifts are standard patterns of working time. They determine when a resource is available for work.

Add a Shift

Use this feature for non-standard types of shift that don't fall within the traditional 24-hour clock. You can create separate shifts for each working time pattern within your organization.

  1. Click Configuration.

  2. In the General section, click Work Schedules.

    The Work Schedules page appears.
  3. Click Shifts.

    The Shifts page appears.
  4. Click Add Shift.

    The Add Shift dialog box appears.
  5. Fill up these fields and then click OK:

    Field Description
    Name Enter a name for the shift, as it appears in the application.
    Label A unique identifier for this shift.
    Type Select an option from the drop-down list. Common shift types include Regular for standard periods of time, or On-call for longer time frames that a resource might be available, after the regular shift ends. Select the color coded on-call icon that you want to attach to the shift. When you add this shift to a resource, this icon is displayed on the Dispatch Console, Manage, Calendar, and Resource Calendar pages, and on the resource avatar.
    Active Click the check box to activate (make available for use) this shift.
    Time From Enter the start time for this shift.
    Time To Enter the end time for this shift.
    Points Within the application, points are used as limiters. If activities are assigned point values (based on different completion durations, complexity, value, etc.), then assignment caps can be determined on a shift-by-shift basis. Once point thresholds are reached for a resource to which that shift is assigned, then routing will allocate no more activities to that resource.

Add an Activity to a Shift

Add an activity to a shift, when you want to add the activity to the calendars of all of the resources that have the shift assigned to them.

  1. Click Configuration, Work Schedules, Shifts.

    The Shifts list displays.

  2. Click the Activities link in the row of the shift that you want to add the activity to.

  3. Click Add Activity.

    The Add Activity page displays. If this activity is an internal activity, the layout of the page changes. If it is a customer-facing activity, the layout stays the same.

  4. Complete the applicable fields.

    Field name Action
    Activity Type Select the activity type from the Activity Type drop-down list.
    Name Enter the customer’s name. Used for customer-facing activities only.
    Work Order Enter the work order number associated with this activity.
    Duration Enter the amount of time that the activity lasts.
    Position in Route-Not Ordered The activity is not ordered, and appears in the Not Ordered column in the Time view.
    Position in Route-Ordered The activity is displayed on the resource's route. If you specify a time slot, the activity displays in that time slot. Otherwise, it displays as pending at the beginning of the route.
    Time Slot Select the period of time within which this activity can be started.
    Activity Notes Enter any notes associated with this activity.
    Recurrence-Repeats-Daily Apply to schedules such as every other day or every 3rd day. If you select this option, add the frequency of occurrence in the field Days between occurrences.
    Recurrence-Repeats-Everyday Applies to every day schedules that repeat without exception and without any modification options.
    Recurrence-Repeats-Weekly Apply calendars that have a regular weekly pattern. Select the days that apply to this shift using the check boxes for the individual days. Indicate the frequency of this pattern weekly by adding a value to the Weeks between occurrences field.
    Recurrence-Repeats-Yearly Occurs every year from the selected date entered in the From day until the date entered in the To day field.
  5. Click OK.

Statistics

Oracle Field Service uses collected statistical data on actual activity and travel duration for calculating a resource’s estimated time arrival for the pending activities and the delivery window. In addition, the Routing module uses the collected statistics to assign activities to a resource in the most effective manner, according to the specified routing parameters. Statistical parameters are calculated separately for each resource, group/bucket, and whole company. If the data is not enough to predict the duration or travel for a resource, then the group/bucket or company values are used. Finally, if the data is not enough at the company level, then the default values are used.

View Statistical Parameters

You can view the settings based on which Oracle Field Service collects statistical data. Be aware that if you try to adjust the settings, it may significantly change the workload for each resource, and significantly impact the logic of gathering statistics for the work done.

  1. Click Configuration.

  2. In the Subsystems and Integrations section, click Statistics.

    The Statistics page appears.

    Field Description
    Duration parameters
    Minimum relevant duration time in minutes

    Maximum relevant duration time in minutes

    To ensure that outlier activity durations (sometimes due to non-compliance) don't adversely affect statistical calculations, durations with values less than or more than the minutes entered in these fields will be ignored by the statistics engine.

    Lower limit for personal ratio to calculate duration (%)

    Upper limit for personal ratio to calculate duration (%)

    The lower and upper limit percentages are with respect to the company level duration for an activity. If the duration estimated for a resource’s assigned activity is beyond the lower or upper limit, the estimate is corrected so that it lies within the set limits. The Lower limit default value is 50 with an available range from 0-100. The Upper limit default value is 200 with an available range from 100-999. If the preference is always to use the personal learned duration without any lower or upper limits applied, the ranges must be set for the outer extremes with the lower limit set to 0 and the upper limit set to 999.

    Example: Suppose the company-level estimation for an activity is 50 minutes and the lower limit percentage is set to 80%. If the estimation for a resource is 30 minutes, the final estimation for the activity will be calculated as the maximum of 30 minutes and 80% of 50 minutes, which will be 40 minutes. The lower limit would be in effect and 40 minutes would be assigned to the activity.

    Travel time parameters
    Default travel average time The average value and standard deviation (in minutes) used for travel time prediction when there isn't statistical data for travel between two specific travel statistics keys.
    Minimum relevant travel time in minutes

    Maximum relevant travel time in minutes

    In an effort to ensure that outlier travel durations (sometimes due to non-compliance) will not adversely affect statistical calculations, durations with values less than or more than the minutes entered in these fields will be ignored by the statistics engine.
    Coordinate calculation weight This parameter defines the weighting proportion between the statistic (average travel time) and coordinate methods (straight line/airline) of calculating/predicting travel time between two locations. The options are as follows:
    • 0 = Use only travel key based estimation

    • 0.001 = Prefer travel key based estimation

    • 0.5 = Use both estimations evenly

    • 0.999 = Prefer coordinate method based estimation

    • 1 = Use only coordinate method based estimation

    Airline distance speed The speed used to determine airline (straight line) distance time.
    Departure/parking time The amount of time that is allowed for parking and departure from one activity to another.
    Delivery Window Parameters
    Delivery window factor Determines how much deviation should affect the calculation of future delivery windows based on their ETAs.
    Delivery window granularity This defines the number of minutes to which delivery window values will be rounded.
    Delivery window minimal size When delivery window is calculated, this is the smallest value (in minutes) that will be provided.
    Delivery window maximal size When delivery window is calculated, this is the largest value (in minutes) that will be provided.
    Delivery window should not start earlier than [ ] minutes prior to start of service or SLA window Prevents the delivery window from starting outside the previously agreed service window. When the option is enabled, the statistically calculated delivery window cannot start earlier than the specified number of minutes before the service window or SLA window start.
    Stats Fields
    Activity duration stats fields

    Activity travel stats fields

    Resource travel stats fields

    This group represents the formation of the keys (made up of fields) used for the grouping of work duration and travel duration values to find the averages.

    The user-defined activity keys make it possible to sort the collected statistical data according to various activity characteristics, such as work order type, activity properties, activity postcode, etc.

    Note: You can specify durations for specific activities and technicians through APIs. For more information, see the REST API for Oracle Field Service guide.

Update Travel Statistics

Travel statistics are updated when the not-assigned activities with default travel time are assigned to a resource. Oracle Spatial and Graph Route Server, which sends the travel time, updates the travel statistics in real-time.

  1. Open Configuration > Statistics.

    The Statistics page appears.

  2. Set up the Default Travel Time and Minimal Statistical Travel Time to ensure there is no statistical information for the travel time between these activities.

    The setup time is applied to the activities of the bucket.

  3. To assign the activities in the bucket to a resource, select the appropriate activities and click Move.

    The travel time value is received from street level route service and set up as per this value.

Themes

A theme defines the look and feel of the user interface. You can use the standard themes namely Classic, Vanilla, and Redwood. Or, you can create a theme based on your organization's branding colors.

View Themes

You can create custom Themes that use your own logos as headers in the user interface, including the Login page. In addition, you can define a custom theme color, which appears as the header. The Themes visibility controls the access to Themes. For each user type that manages Themes, set the Read/Write permissions. When you set the visibility to ReadOnly, the Themes page is grayed, and when you don’t grant the visibility, the Themes page is not visible at all.

  1. Click Configuration.

  2. In the Displays section, click Themes.

    The Themes page appears and displays these fields:

    Field Description
    Name The name of the theme.
    Default Displays whether the theme is selected as the default theme. The default theme has a check mark next to it. When you click Select default, you can set whether all users or only new users will have this theme set as the default.
    Active Displays whether the theme is active. An active theme has a check mark next to it. The Set enable or Set disable actions determine whether the theme is active or not.
    Actions Displays the actions available for the Theme. These actions are available:
    • Edit – Allows editing the options for the selected theme. See the Add a Theme section for an explanation of the options.

    • Set default - Sets this theme as the default theme. You can set whether all users or only new users will have this theme set as the default.

    • Set enable - Enables a currently disabled theme.

    • Set disable - Disables a currently enabled theme.

    • Export – Exports the details of the theme to a zip file. The zip file can be used to import the theme into another Oracle Field Service instance.

    • Delete – Deletes the theme.

Add a Theme

You can create custom Themes to use your own logos as headers in the user interface and use your branding colors for the application page background, header, and the Submit button. The Themes visibility controls the access to the Themes. For each user type that manages Themes, set the Read/Write permissions. When you set the visibility to ReadOnly, the Themes page is grayed, and when you don’t grant the visibility, the Themes page is not visible at all.

  1. Click Configuration.

  2. In the Displays section, click Themes.

    The Themes page appears.
  3. Click Add new.

    The Add theme dialog box appears.
  4. Complete these fields:

    Field Action
    Name Enter a name by which you want to identify the theme.
    Copyright Enter the Copyright information. The text must contain placeholders for {YEAR} and {VERSION} that will be automatically replaced with the current year and the major version. Example: © 2003-{YEAR} Oracle Corporation. All rights reserved. Version {VERSION}. The maximum length of this string is 255 characters.
    Logo tab
    Logo Select the logo in .png format. This logo is used with pages of width 1024 and more, or between 320 and 768.
    Logo for Login page Select the logo in .png format. This logo is used in the login portal.
    Color scheme
    Header color Select the color for the application header. Click this field and select a color from the color editor. Or, enter the hexadecimal code for the color. The selected color is displayed in the preview section.
    Page background color Select the color for the application page. Click this field and select a color from the color editor. Or, enter the hexadecimal code for the color. The selected color is displayed in the preview section.
    Submit button color Select the color for the Submit button. Submit buttons across the application are displayed in this color. Click this field and select a color from the color editor. Or, enter the hexadecimal code for the color. The selected color is displayed in the preview section.
  5. To reset the colors, click Set default.

  6. Click Save.

The page background and the Submit button colors are applied to the pages that are mainly used by field resources, such as Activity details, Inventory details, Activity list, and forms. The colors won't be shown on these groups of pages:
  • Pages on which the content takes the entire screen width, for example, Dispatch console, Manage, Maps, and Calendars.
  • Configuration pages.
  • Pages that have their own specific background, for example, About, Dashboard.
  • Hints and context-menus.

Where is My Technician

Where is My Technician lets you send a URL to your customers, through which they track the status of their ordered service. Where is My Technician is available as a theme on the Configuration > Themes page. You can configure the Where is My Technician pages with your organization’s branding and set whether your customer can track a technician on the map, see the technician’s details, and provide feedback when the technician completes the job.

Note: Where’s My Technician functionality is not available for Contingent Workers.
You can perform these tasks with the Where is My Technician feature:
  • Send a tracking URL in the appointment confirmation and reminder emails

  • Show the details of the appointment, service address, and day/time of arrival

  • Show a custom name for technicians, for example, Mr. William or Will

  • Show or hide the technician’s photo

  • Show or hide the technician’s position on the map

  • Show custom technician and customer location markers on the map

  • Show the estimated arrival time of the technician

  • Let customers track the technician’s location in near real-time

  • Allow or block providing feedback after a technician’s visit

  • Allow chatting through the Smart Chatbot

  • Configure branding for the tracking web page

  • Customize the text for the tracking page

How to Use the Feature?

The Where is My Technician feature is available if you have an Oracle Field Service Professional or an Oracle Field Service Enterprise subscription with Google Maps. The feature is not yet available for your subscriptions with Oracle Maps.

Where is My Technician is a theme that is available on the Configuration > Themes page. When you configure this theme, you can send a URL to your customers, which they can use to track the technician. When your customers open the tracking URL, the page refreshes automatically every five seconds to display the latest information. If you change the fields on the theme, the new fields display when the customer refreshes the tracking page. Your customers can view the technician’s details from the time the technician is assigned to the activity, but they track the technician’s route only when the technician is on the way to the activity. To track the technician’s location on the map, we recommend that your customers use the Oracle Field Service Installed Application with location sharing enabled. For customers who send the resources location using APIs, the Property to identify resource in SmartLocation and GPS API field on Business Rules must be set to `External ID'.

Although the Where is My Technician theme supports all types of activities, we recommend that you do not use it for segmentable activities. The Where is My Technician theme includes the Scheduled, Days before, On the way, Arrived, and Feedback pages. However, for your customers it is just one page and the information on the page corresponds to the status of the activity at that time:
  • Scheduled: The activity is created in a bucket and the Service window/Delivery window is set.

  • Days Before: A technician is assigned (and can be also changed) and the Service Window is known.

  • On the Way: The technician has completed (Completed, Not done, Suspended, or activity reordered) the previous activity and the time of arrival (ETA) is available.

  • Arrived: The technician has arrived and started the activity.

  • Feedback: The technician has changed the activity to Complete, Not done, or Suspend.

Your customers can see the Where is My Technician page for non-scheduled activities as well, but without the date and time of service.

High-Level Steps to Use The Feature

To use the Where is My Technician feature, you must:
  • Create a theme for Where is My Technician.

  • Configure the theme with the required branding and other settings.

  • Add a placeholder for the URL on your message text.

  • Specify the theme label in the URL to determine the theme that you want to be accessed through the tracking link.

Create a Theme for Where is My Technician

You must create a theme for Where is My Technician to add the details that you want to show your customers. You can create multiple themes such as themes according to the services you provide (for example, telephone services, computer repair services), themes based on regional languages, or themes based on the preferences (such as location tracking enabled, feedback enabled). Users with the Oracle Field Service Professional subscription can create a maximum of five themes. And, users with the Oracle Field Service Enterprise subscription can create a maximum of 25 themes.

  1. Click Configuration > Themes.

  2. Under Where is My Technician, click Add new.

  3. On the Add WMT Theme page, enter a label for the theme.

    Later, you have to add this label to a message scenario to get the URL, so enter a meaningful label.
  4. Enter a description for the theme.

  5. Click Add.

    The Edit theme page appears. You can continue with creating the theme, or you can click Save and edit it later.

Configure the Where is My Technician Theme

You must configure a theme after you create it. You configure a theme to select a template, specify your branding details, select the tracking details, and decide whether you want to let customers provide feedback for the technician and the service.

Before you add the Feedback page, ensure that you have created the custom properties to store the feedback comments and rating. You can create the custom properties on the Configuration > Properties page.
  1. Click Configuration > Themes.

  2. Under Where is My Technician, click Edit on the stack icon for the Where is My Technician theme of your choice.

  3. To add branding to the theme, click Branding and complete these fields:

    Field Name Action or Description
    Theme description Enter a description for the theme that helps you identify its purpose.
    Template Select the template that you want to use from Bright, Hero, and Minimal templates. Notice that the Scheduled, Days before, On the way, Arrived, and Feedback pages refresh with each detail that you add to the theme.
    Main color Click the hexadecimal number and select a color of your choice. This is the color in which the text is displayed.
    Background color Click the hexadecimal number and select a color of your choice. This is the background color of the page. Your customers may access this page from their mobile phones and the screen width is limited, so choose the colors carefully. If you have selected the Hero template, then the Background picture field becomes available and you can upload a custom picture.
    Company logo Click Browse and select a file with the extension JPEG, PNG, GIF, TIFF, or SVG. You can select a file of maximum size 100 KB. This logo is displayed at the top of the page.
    Company favicon Click Browse and select a file with the extension ICO or PNG. You can select a file of maximum size 30 KB. This is the small icon is displayed on the web page header. It is typically a smaller image of your organization or product logo.

    You can configure the browser tab name in the Company field on the Localization tab. It will be shown next to the favicon.

    Custom domain name Enter the domain name that you want to use in the Where is My Technician URL. For example, https://wmt.example.com/k694jg. Here, k694g is the unique token.
    Note: If the Custom domain name field is empty, then the Where is My Technician URL cannot be opened in an iFrame.
    You must perform these additional tasks to use the custom domain name:
    • Configure the HTTPS web server with the proxy page.
    • Configure your web server to route all the requests to an index page.
    • Add the index.html page to the root of the web server.

      For more information on how to configure a custom domain name, see Example of NGINX Configuration and Example of How You Can Open a Where Is My Technician URL With a Custom Domain in iFrame.

  4. To specify attributes such as arrival time and technician's photo, click Attributes and complete these fields:

    Field Name Action or Description
    Arrival time Select one of these values to define the technician's time of arrival:
    • Do not display: Select this option to hide the arrival time on the Where is My Technician page.
    • Time notified, Delivery window, Service window: Select this option to let the application choose the available value according to the activity status, value availability, and their priority:
      • Time notified:
        • Delivery Window
        • ETA
        • Service Window
        • Value returned through an outbound response message
      • Delivery Window
      • Service Window

        You can configure the arrival time further using the {ARRIVAL_TIME_RANGE} place holder. For more information on the {ARRIVAL_TIME_RANGE} place holder on the Localication tab, see the Available Placeholders on the Localization Tab topic.

    • Time notified: Select this option to display the time you have informed your customer that the technician would arrive. The application does not update this value automatically. The options are:
      • Delivery Window
      • ETA
      • Service Window
      • Value returned through an outbound response message
    • Delivery window
    • Service window
    • ETA

    You can configure the 'ARRIVAL_TIME_RANGE' placeholder to configure the value that you want to use for Time notified. If the Delivery Window, Service window, or ETA is empty, then the arrival time is not shown on the page.

    Type of service
    Select one of these values:
    • Do not display: Select this option to hide the type of service that the technician is going to perform.
    • Activity type: Select this option to display the activity type as the type of service.
    Customer address
    Select one of these values:
    • Do not display: Select this option to hide the customer’s address.
    • Customer address: Select this option to display the customer’s address on the Where is My Technician page. This field comprises the Address, City, ZIP/Postal Code, and State fields. If any of these values is empty, then it is not shown on the page.
    Technician name Select whether you want to display the technician’s name or the credence. You can choose any custom resource property that has the GUI set as Text element.
    Note: The Where is My Technician functionality is not available for Contingent Workers.
    Show technician photo Select the check box if you want to display the technician’s photo. If you don’t select the check box, no photo is shown. Be aware that the photo available in the Avatar field of the Resource Info page is used as the technician’s photo.
  5. To add the map details, click Map and complete these fields:

    Field Name Action or Description
    Customer position Select one of these values:
    • Do not display: Select this option to hide the customer’s coordinates on the map. When you select this option, the technician’s position is also hidden. Use the Customer address field on Attribute tab to hide the customer’s address on the page.
    • Exact: Select this option to display the exact position of the customer on the map.
    • Approximate: Select this option to display a bubble around the customer’s location on the map.
    Customer icon Select an icon from the drop-down list or, click Browse and select a custom icon. This icon indicates the location of the activity. If you select an icon from the drop-down list, its color changes according to the color you have selected in the Branding tab. If you select a custom icon, you can also select the position of the icon on the map.
    Technician position Select one of these values:
    • Do not display: Select this option to hide the technician’s coordinates on the map.
    • Show with driving track: Select this option to display the technician’s driving track, while showing the exact position of the customer on the map.
    • Show without driving track: Select this option to display the technician icon without the driving track, when you have selected the customer position as 'Exact' or 'Approximate'. When you have selected the customer’s position as Approximate, the technician icon is available till the technician hits the bubble on the map. After that the technician icon is hidden.
    If Google sends the navigation details and the technician has shared their location, Oracle Field Service uses that data. If the technician has not shared their location, or if Google has not sent the navigation details, Oracle Field Service uses the ETA (Start Time - Current-Time) to derive the estimated duration. The behavior is further clarified here:
    • Shows the ETA (expected time of arrival) from Oracle Field Service (StartTime - Current time), if Google has not yet sent the navigation details and ETA. In this case, only the customer icon shows on the map and ETA from Oracle Field Service.

    • Shows Google ETA as soon as it's available, then the route is available on the map, with the ETA from Google. In this case, the technician icon with route displays on map and ETA updates to Google's ETA.

    • If the technician becomes offline, the last position is remembered and shown. In this case, the user who opens the link sees the ETA to the technician’s last position and as soon as the technician becomes online, the ETA is updated. This means that the ETA may be 4 hours approximately and may suddenly become about 20 minutes, because the technician’s actual position is updated.

    Do not show position Enter the number of minutes for which you want to hide the technician’s position after they complete the previous appointment or after they activate the route. The activity status of the previous activity can be Complete, Note done, Canceled, Suspended, or the activity is reordered. As soon as the set time is over, the technician icon is shown on the map. This helps you hide the coordinates of the previous customer or the technician's home location. This field is set to 0 (zero) by default, which means, the technician’s position is shown immediately after the technician completes the previous appointment.
    Technician icon Select an icon from the drop-down list or, click Browse and select a custom icon. This icon indicates the technician’s location. If you select an icon from the drop-down list, its color changes according to the color you have selected in the Branding tab. If you select a custom icon, you can also select the position of the icon on the map. You can use real car icons and show the car changing direction according to the route. Be aware that the anchor for these icons is in the center. If a technician doesn’t share the location, or is offline for a long time, then only the customer’s location is displayed on the map. If neither the technician's location nor the customer's location is available, only a blue map is displayed.
  6. To customize the text that is displayed on the Where is My Technician page, click Localization and complete these steps:

    1. Click Locale and select the locale based on which you want to display the date and time. For more information on the languages and locales supported, see Default Translations and Date-Time Format.

    2. In each field, enter the text that you want to display, based on your business requirements. These values are always displayed in English.

    3. Click the question mark icon to view the description and default text of the field.

    4. Place the cursor at the required position, click the question mark, and then click Available placeholders. The data field is inserted at the selected location. Let’s say you want to change ‘{TECHNICIAN_NAME} is your technician.’ to ‘Your technician is ‘{TECHNICIAN_NAME}’. Delete the existing text and add ‘Your technician is’. Place the cursor after ‘is’. Click the question mark icon and then click ‘{TECHNICIAN_NAME}’ under Available placeholders.

    5. Optionally, clear the custom text to view the default text.

  7. To add the Feedback page, click Feedback and complete these fields:

    Field Name Action or Description
    Enable feedback Select this check box to let your customers send feedback. If the customer does not provide the feedback on the day the activity is completed, then they will see the Thank You page, instead of the Feedback page.
    Feedback mode Select how you want to receive the feedback. You can choose from Comment and Rating, Comment, and Rating.
    Property for saving comments Select the property that you want to use to store the comments. Use only string type of custom activity properties for comments.
    Property for saving rating Select the property that you want to use to store the ratings. Use only integer type custom activity properties that have the GUI as Text for ratings.
    Localization Customize the text that you want to display on the Feedback page. For more information on this, see Step 6.
  8. To provide more options to your customers on the Where is My Technician page, click Interaction and complete these fields:

    Field Name Action or Description
    Enable Cancel Select this check box to let your customers cancel the activity. Then, add the text for the confirmation page. Cancel is available for an activity that is in Pending status. Cancel is hidden as soon as the activity status changes to Started.
    Enable chatbot Select this check box to let your customers chat with a chatbot. Ensure that you have a license for Oracle Digital Assistant. Verify that your administrator has created a web channel and configured the chatbot flow in Oracle Digital Assistant. Get the values of Channel URI and Channel ID from Oracle Digital Assistant.
  9. Click Save.

    Your settings are saved and the Where is My Technician theme is created.

Add a Tracking URL to a Message Scenario

When your customers order a service, you notify them through a message that the service they have ordered is accepted. You add a URL to this message, using which your customers can view the details and track the technician assigned to the activity. For that, you must add a placeholder to the 'Body' of the message step and specify the ‘Where is My Technician’ theme label.

  1. Go to Configuration > Message Scenarios.

  2. Click Modify on an existing message step or create a new step.

  3. Click Patterns and go to the Body section.

  4. Add the placeholder {{WMT_URL:label_theme}} (including the double braces) to the required position in the message body.

    Here, label_theme is the label of the Where is My Technician theme that you want to use. The default Where is My Technician theme is used if you have configured a message step with a nonexistent theme label. There can only be one theme used per activity. So, if you have used more then one theme label for the same activity in different message steps, the theme in the last delivered message is used.
  5. Click Save.

    The WMT_URL placeholder is replaced with a unique tracking URL, when the message step is launched. The URL consists of the domain and a secure token that is specific for the activity. For example, https://w.etadirect.com/a784hk596 where https://w.etadirect.com/ is the domain and a784hk596 is the secure token. This URL is available till the activity date and three days after. If your end-customer opens the URL after it expires, then they get the message, 'Oops. Seems that this URL is no longer valid and details are not available.' on the page. However, if the customer clicks an active URL for an activity in the past, 'Thank you!' is displayed.

Use Cases and their Launch Conditions

This table gives the launch conditions that you can use, when you create Message Scenarios to add the tracking URL for Where is My Technician.

Scenario Launch Condition
Confirm a scheduled appointment 'Activity created' when an activity is scheduled on a bucket and is not yet assigned to a field resource.
Introduce a technician assigned to an appointment 'Activity created' when a Field resource is assigned to an activity or when an activity is re-assigned to another resource.
Remind about a service days before 'There is a specified number of days prior to activity' or other from the Reminders section to notify that the scheduled service date is approaching.
Notify if the technician has changed 'Activity created' if the activity is re-assigned to another field resource.
Notify if the service has moved to a future date 'Activity is moved' if the activity is rescheduled to a future date.
Notify that the technician will arrive soon 'Next activity is about to start' if the technician has completed the previous activity and is on the way to the end-customer.
Request feedback when the technician has finished a service and left 'Activity completed', 'Activity not done', and 'Activity suspended' when you want to ask for feedback.
Resend message if the service or gateway fails "Sending will time out in" and/or "Number of attempts on 'failed' status"
Cancel an activity Activity is canceled. You must add a new Blocking Condition, Activity Type [aworktype].

Available Placeholders on the Localization Tab

This table gives the placeholders that you can add to the text on the Localization tab of the Where is My Technician theme.

Placeholder When You Can Use Values
{TECHNICIAN_NAME} Available in all activity statuses except "notAssigned". Can be used for translations:
  • First line of status text shown when the activity is already assigned to a technician Default value: Will arrive between

  • Second line of status text shown when the activity is already assigned to a technician Default value: {ARRIVAL_TIME_RANGE}

  • First line of status text shown when the technician is on the way Default value: Arriving in about

  • Second line of status text shown when the technician is on the way Default value: {ETA}

  • Technician info text when the appointment is assigned Default value: {TECHNICIAN_NAME} is your technician

  • Technician info text when the technician is on the way Default value: {TECHNICIAN_NAME} is on the way

  • Technician info text when the technician has arrived Default value: {TECHNICIAN_NAME} has arrived

  • Feedback form ratio field title Default value: How was {TECHNICIAN_NAME}'s service?

Holm, Billy

Mr. Billy

Billy

{ETA} Available for "onTheWay" activity status. ETA is calculated based on Google data. If Google data is not available, then Oracle Field Service ETA is used. Can be used for translations:
  • First line of status text shown when the technician is on the way Default value: Arriving in about

  • Second line of status text shown when the technician is on the way Default value: {ETA}

2 hours

42 minutes

less than 1 minute

The ETA is always displayed in English.

{ARRIVAL_TIME_RANGE}

This place holder is applicable only if you select the 'Time notified, Delivery window, Service window' option for Arrival time on the Attributes tab.

Available for "notAssigned" and "assigned" activity statuses and when delivery window or service window are not empty. Can be used for translations:
  • For "notAssigned" activities the arrival window is used according to the availability of these values and their priority:
    1. Time Notified:
      1. Service window
      2. Value returned via Outbound response message
    2. Service Window
    Default value of the first line of the status text shown when the activity is ordered and isn't assigned to a technician yet: A technician will arrive between. Default value of the second line of the status text shown when the activity is ordered and isn't assigned to a technician yet: {ARRIVAL_TIME_RANGE}

  • For the activities assigned to a technician, the arrival window is used according to the availability of these values and their priority:
    1. Time Notified:
      1. Delivery Window
      2. ETA
      3. Service Window
      4. Value returned via Outbound response message
    2. Delivery Window
    3. Service Window

      Default value of the first line of the status text shown when the activity is already assigned to a technician: Will arrive between

      Default value of the second line of the status text shown when the activity is already assigned to a technician Default value: {ARRIVAL_TIME_RANGE}

      For more information about how to use 'Time Notified', see the How to Use 'Time Notified' topic.

8:15 AM - 8:45 AM

How to Use 'Time Notified'

You can show Time Notified on the {ARRIVAL TIME RANGE} placeholder. You can set the value for Time Notified through a Message Step with the Outbound API using 'send_message'. If you set the value, it will be used on the Where's My Technician page, instead of the Delivery Window or Service window. If Time Notified is not populated, then Delivery Window or Service window is shown. You can choose to use ETA, Delivery Window, or Service Window as Time Notified. For example, you can save the ETA, which you communicated to your customer the Where is My Technician page shows this time, even if the technician adjusts the previous activity. This way, the feature also prevents the application from updating the agreed time automatically.

  1. Navigate to Configuration, Message Scenarios.

  2. Open the message scenario that you have configured for Where is My Technician.

    If not configured, set the Recipient to Customer in the Settings Tab.
  3. Select the Customer notification time field and select the value that you want to display for Time Notified.

    You can select either Service window, Delivery Window, or ETA. You can set a custom window using the Outbound API ‘send_message’. For using ‘send_message’, see the Outbound API documentation.
  4. Open the Where is My Technician theme and go to the Localization tab. Click the {ARRIVAL TIME RANGE} placeholder.

    {ARRIVAL TIME RANGE} is available only for "Not Assigned" and "assigned" activity statuses. The value you have selected for Customer notification time in the message scenario is shown on the Where is My Technician page. If you have configured the Time Notified field to receive the value from an outbound API response using ‘send_message’, it is displayed.
    The {ARRIVAL TIME RANGE} shows the arrival window according to availability of these values and their priority:
    Note: If ‘Time Notified’ is set with a custom window, this value is not removed or changed if the activity is moved to another resource or bucket. You must consider this behavior in your design and make any necessary updates to the window according to your business process.

    Table

    Page Activity on the Bucket (Not Assigned) Activity Assigned to a Technician (Assigned)
    Days before screen
    1. Time Notified:
      • Service window
      • Value returned via Outbound response message
    2. Service Window
    1. Time Notified
      • Delivery window
      • ETA
      • Service window
      • Value returned via Outbound response message
    2. Delivery Window
    3. Service window

Use Notification Channels

You can send the Where is My Technician tracking details through emails that are generated using Message Scenarios, through email and SMS through gateway services, and through custom delivery channels. The custom delivery channels can be email or web-services that accept SOAP API requests.

  1. To use the email notification channel with Message Scenarios:

    1. Click Configuration > Message Scenarios.

    2. Create or modify a message step.

    3. On the Settings tab, select Email for Delivery Channel.

    4. Select Customer for Recipient.

    5. Click Patterns and go to the Body section.

    6. Add the placeholder {{WMT_URL: theme_label}} (with double braces) at the point where you want to add the link.

      If you have created a separate theme to enable the Cancel option, remember to use it when required.
    7. If you are using a theme created for the Cancel option, then add a blocking condition for Activity Type [aworktype] in the Blocking Conditions tab.

      This excludes the required types of activities.
    8. Continue with creating or modifying the step.

    9. Click Save. When the Message Scenario is launched, the email is sent to the user.

  2. To send an SMS using a third-party gateway service through Oracle Integration Cloud:

    1. Define a custom property (for example, X_WMT_MESSAGE) to store the tracking URL.

    2. Configure Oracle Integration Cloud to read the custom property for tracking URL and the customer’s phone property. Configure it to send messages using third-party tools, such as, Twilio OIC Adapter or Oracle Cloud Integration.

    3. Click Configuration > Message Scenarios.

    4. Create or modify a message step.

    5. On the Settings tab, select Set Property for Delivery Channel.

    6. Select Customer for Recipient.

    7. Click Patterns and go to the Body section.

    8. Specify the property label (for example, X_WMT_MESSAGE) in the Subject section.

    9. Click Save. When the Message Scenario is launched, the SMS is sent to the phone number.

Verify Whether the URL is Generated for the Message Step

Sometimes, you may want to verify whether a message was generated with the tracking URL and sent to the customer. You can use the Messages button on the Activity details page to verify.

  1. Configure the Messages button for the Activity details page.

  2. Open the Activity details page for the activity for which the customer has to get the tracking URL.

  3. Click Messages.

  4. Use the Status, Delivery channel, Recipient, or Any filters.

    The messages that match the criteria appear.
  5. Find the message step for which you want to verify the URL.

  6. Click a line of the message step and verify the Body text of the message.

    The URL must be present.

View Activities Canceled Through the Where is My Technician Page

When your customer cancels an activity through the Where is My Technician page, you can determine that it is canceled by your customer, on the Activity details page.

  1. Open the Activity details page for the activity that is canceled by your customer.

  2. Go to the History tab.

  3. Look for the line item that has WMT(customer) in the User column.

Default Translations and Date-Time Format

Where is My Technician supports the default translations and date and time format for these languages:

Arabic locales:
This screenshot shows the Arabic locales for which the default translation and date and time are supported.

Czech, Danish, German, Greek, and English locales:


This screenshot shows the Czech, Danish, German, Greek, and English locales for which the default translation and date and time are supported.
Finnish, French, Hindi, Hungarian, Italian, and Japanese locales:
This screenshot shows the Finnish, French, Hindi, Hungarian, Italian, and Japanese locales for which the default translation and date and time are supported.

Korean, Dutch, Norwegian, Polish, Romanian, Russian, Swedish, and Turkish locales:


This screenshot shows the Korean, Dutch, Norwegian, Polish, Romanian, Russian, Swedish, and Turkish locales for which the default translation and date and time are supported.

Spanish locales:


This screenshot shows the Spanish locales for which the default translation and date and time are supported.
Hebrew, Chinese, and Portuguese locales:
This screenshot shows the Hebrew, Chinese, and Portuguese locales for which the default translation and date and time are supported.

Example of NGINX Configuration

Use the sample code provided here to configure your web server to route all requests to the index page.

server {
    listen       80;
    server_name  wmt.example.com;
 
    location / {
        root   /usr/share/nginx/html;
        try_files $uri /index.html;
    }
}

Example of How You Can Open a Where Is My Technician URL With a Custom Domain in iFrame

Use the sample code provided here to configure the Where is My Technician URL with a custom domain name to open in iFrame.

<!DOCTYPE html>
<html>
 
<head>
    <title>WMT within iframe</title>
    <style type="text/css">
        html {
            overflow: auto;
        }
         
        html,
        body,
        div,
        iframe {
            margin: 0px;
            padding: 0px;
            height: 100%;
            border: none;
        }
         
        iframe {
            display: block;
            width: 100%;
            border: none;
            overflow-y: auto;
            overflow-x: hidden;
        }
    </style>
</head>
 
<body>
    <iframe id="wmt-chrome"
            src="#"
            frameborder="0"
            marginheight="0"
            marginwidth="0"
            width="100%"
            height="100%"
            scrolling="auto">
    </iframe>
</body>
 
<script type="text/javascript">
    document.getElementById('wmt-chrome').setAttribute('src', 'https://{custom_domain_name}' + window.location.pathname);
</script>
 
</html>

Overview of Using Oracle Digital Assistant with Where is My Technician

You can integrate the Where is My Technician page with Oracle Digital Assistant to perform a variety of tasks in natural language conversations.

Some of the business scenarios you can cover are:
  • Reschedule an appointment: Oracle Digital Assistant suggests the available time, asks the user for a reason, and confirms the rescheduling.

  • Cancel an appointment: Oracle Digital Assistant asks a user for the reason of and confirms the cancellation.

  • Leave Feedback: Oracle Digital Assistant thanks for a good rating and asks the reason for bad feedback.

  • Share the good Feedback on company sites: Oracle Digital Assistant asks for posting good feedback on your organization's profiles such on Google, Twitter, Amazon, and so on.

  • Notify a technician about the details: Oracle Digital Assistant can send a message from the user. This is saved as a note for the technician.

Note: The Sample skill is sample code and demonstrates how Oracle Digital Assistant can help users on the Where is My Technician page. It's neither maintained nor supported by Oracle as a licensed product.

Before You Begin with Oracle Digital Assistant

Before continuing with the next steps, you need:

  • An Oracle Field Service instance that has the 'Where is My Technician' feature and the Enable Oracle Digital Assistant setting enabled for the feature.
  • An Oracle Digital Assistant instance platform version 20.06 or higher.

Define the Skills You want to Use

Before you start configuring Oracle Digital Assistant, you must have a clear idea of the skills that you want to provide through the assistant.

This table provides the list of skills and their descriptions:

Skill Description
Reschedule

The assistant suggests the available time, asks the user for a reason, and confirms the rescheduling.

This Oracle Digital Assistant skill uses the time slots that are configured in Oracle Field Service. After the user (your customer) confirms, the activity moves to the technician's parent bucket with the selected time slot. It will be further routed.

Save reschedule reason

You can save the reason for reschedule to an activity property.

Cancel The Assistant suggests to cancel an appointment and asks for the cancellation reason. After the user (your customer) confirms, the activity is cancelled.
Save cancel reason

You can save the reason for canceling an activity to an activity property.

Notification to Technician If the user (your customer) sends a note to the technician through the assistant, it can be added as a note for the activity.
Feedback If the activity status is completed, the user (your customer) can rate the service and share the feedback. If the user rates the service with stars on the Where is My Technician feedback page, the assistant can understand whether it is positive or negative based on the number of stars set.
Save Feedback in Oracle Field Service

You can save the feedback to an activity property in the application, regardless of whether the feedback is negative or positive.

Share Feedback on external site

You can share the positive feedback on external sites. You can store the external link at the parent organization unit or the bucket level of the technician who performed the activity.

Configuration Steps

Here are the steps to configure Oracle Field Service to use Oracle Digital Assistant.

  1. Configure Oracle Digital Assistant in the Where is My Technician theme.
    1. Pull the Skill from the Skill Store.
    2. Create a Web Channel in Oracle Digital Assistant.
    3. Add the Channel URI and ID to the Where is My Technician theme.
  2. Configure Oracle Field Service API and permissions.
  3. Configure the Oracle Digital Assistant skills.
  4. Validate the integration.

Pull the Skill from the Skill Store

The first step to integrate Oracle Digital Assistant with the Where is My Technician page is to pull the OFS Assistant: Where’s My Technician (WMT) skill from the Skill Store.

  1. Open the Skill Store in the Development section of Oracle Digital Assistant.

  2. Select the "OFS Assistant: Where’s My Technician (WMT)" skill and pull it.

    You can pull the skill either from the context menu or the skill details.
  3. Find the required skill in the Development section of Oracle Digital Assistant.

    It is ready to be configured now.

Create a Web Channel

A channel is the one on which you deploy a skill. It carries the chat back and forth from users on various messaging platforms to the digital assistant and its various skill bots. For Oracle Field Service you create a channel using Oracle Web. Oracle Web is a widget that comes with the Digital Assistant Client SDK and lets you run a skill in a web page.

  1. Create an Oracle Web channel.

    For more information, see the Using Oracle Digital Assistant guide.
  2. Use the values given in this table to configure the channel:

    Field Value
    Channel Enabled Yes
    Route to OFS Assistant: Where’s My Technician (WMT) or the skill you have imported when you pulled it from the Skill Store.
    Channel Type Oracle Web
    Allowed Domains The domain name of your Where is My Technician page. Or, enter an asterisk (*) to allow all domains.
    Client Authentication Enabled No
  3. Note down the Secret Key and the Channel ID generated on this page.

Configure Oracle Digital Assistant (ODA) on the Where is My Technician Page

You must enable Oracle Digital Assistant on the Where is My Technician theme to integrate and use it.

  1. Log in as an administrator user.

  2. Navigate to Configuration > Themes.

  3. Click Add New to create a theme or select a theme from the Where is My Technician section.

  4. Click the Interaction tab.

  5. Select the Enable Oracle Digital Assistant check box.

  6. Enter the Channel URI and the Channel ID.

    The Where is My Technician page supports several parameters that are used for skill configuration in Oracle Digital Assistant. The values of these parameters are passed to the chatbot while opening a Where is My Technician URL.

    WMT Page Parameters passed to the ODA chat during chat initialization
    Scheduled, Assigned, On the Way, Arrived or Feedback

    activityId

    activityType

    Send if the 'Show Activity type' feature is enabled for the Where is My Technician theme

    resourceName

    customerName

    Feedback Value from 1 to 5 is sent to the chat while submitting the feedback if the Rating is set up for Feedback.
    Example of how to use the customerName and resourceName parameters to implement Oracle Digital Assistant skills:
    component: "System.CommonResponse"
    properties:
      metadata:
        responseItems:
          - type: "text"
            text: "Hi ${profile.customerName}! Your technician is ${profile.resourceName}"
    

Configure the APIs and Activity Permissions

You must create an Application to add the details of the APIs that you want to access from the OFS Assistant: Where’s My Technician (WMT) skill. You must also ensure that some specific features are selected for the activity types for which you create the skills.

  1. Click Configuration > Applications.

  2. Click the plus icon, add these details, and then click Submit:

    Field Name Description
    Application Name Name of the bot that you want to register.
    Application ID A unique ID of the application.
  3. On the Applications page, click the application that you want to register on the left pane and complete these fields:

    Field Name Description
    Application general info section
    Application Name Name of the third-party application that you want to register. This field is populated automatically.
    Application ID A unique ID for the application. This field is populated automatically.
    Active Status of the Application. Inactive Applications don't authenticate or authorize anyone. When you make an active Application inactive, previously-issued access tokens don't work.
    Token Service Type of token service or identity provider the Application uses. Default is OFSC.
  4. Select Authenticate using Client ID/ Client Secret under Authentication settings. Note down the Client ID and Client Secret that are generated.

  5. Click Add new next to API access. Select Core API and Metadata API and click Submit.

  6. Click the stack icon next to Core API and then click Available entities. Select these visibilities for these entities:

    • Select Read-Write for the Activity entity.
    • Select Read-Only for the Resource entity.
    • Select Read-only for the User entity.
  7. Click the stack icon next to Metadata API and then click Available entities. Select these visibilities for these entities:

    • Select Read-Only for the Activity type entity.
    • Select Read-only for the Property entity.
  8. Click Save.

  9. To enable permissions for the activity types:

    1. Click Configuration > Activity Types..

    2. Click Modify against the type of activity for which you want to modify the permissions.

      For example, if you want users to cancel or reschedule only free maintenance activities, select the corresponding activity type.
    3. Select the Support of time slots, Allow reschedule, Allow move between resources features.

    4. Click Update.

    5. Repeat this for all the activity types that you want to use with the OFS Assistant: Where’s My Technician (WMT) skill.

Create Custom Properties to use with Oracle Digital Assistant

To integrate with Oracle Digital Assistant and store data in Oracle Field Service from a conversation, you must create several activity and resource properties. These properties are also configured as default for all the flows in the skill. These properties are mapped to the skill custom parameters that are used for all the features. Your data will not be saved if you do not create these properties.

  1. Click Configuration > Properties.

  2. Click Add new.

  3. Create these string properties:

    Label Entity Type GUI Description
    XA_ODA_CANCEL_REASON activity string text Used to save the reason for cancelation provided by the user
    XA_ODA_RESCHEDULE_REASON activity string text

    Used to save the reason for rescheduling provided by the user

    XA_ODA_FEEDBACK_COMMENT activity string text Used to save the Feedback Comment provided by the user
    XA_ODA_MESSAGE_2TECH activity string text Used to save a notification message from the User to the Technician
    XR_ODA_EXT_REVIEW_URL resource string text Property defined for the resource. If you set this for the resource's parent (following the resource's hierarchy), the URL will be provided to the user to leave a review.

Configure the Authentication

You must add a Client credentials service to confgure the authentication between Oracle Digital Assistant and Oracle Field Service.

For more information on how to add a new authentication service, see the Using Oracle Digital Assistant guide.

  1. Add a new authentication service in Oracle Digital Assistant.

  2. Use the values in this table to create the service:

    Field Name Value
    Grant Type Client Credentials.
    Identity Provider Oracle Identity Cloud Service.
    Name A name by which you want to identify the authentication service.
    Token Endpoint URL The Identity Provider's URL for requesting access tokens in Oracle Field Service. For example <OFS API endpoint>/rest/oauthTokenService/v2/token.
    Client ID Client ID of Oracle Field Service of the application configured on the Configuration > Applications page for Oracle Digital Assistant and the Oracle Field Service instance name concatenated with '@'. For example. 'assistant@OFSinstance'.
    Client Secret Client Secret of the Oracle Field Service application configured on the Configuration > Applications page for Oracle Digital Assistant.
    Scopes The scopes that must be included when Oracle Digital Assistant requests an access token from the provider. Add all the scopes that are required to access the resources. For example: '/rest'.

Feature Selection in the Skill

You can select or deselect the features with some restrictions configured for each customer. This helps to support business flows, restrict, and switch flows easily. The names of the skill custom parameters and their predefined values are provided in the table later in the topic. You can change the predefined values. This functionality is implemented as a pair of parameters for each feature. The Property parameter can contain the value of property or field in Oracle Field Service and the PropertyValue represents the value of this property or field.

For example, let's say an organization wants to provide cancellation only for troubleshooting activities, so the customer can undo their request easily, if the issue is resolved. The configurator must specify the activity type 'troubleshooting' as a value of the Oracle Digital Assistant parameter. The configurator can use these values:
  • Use 'aworktype' as the value for allowCancelProperty. This means that an activity type defined in Oracle Field Service is used to validate the access.
  • Use a value of 'troubleshooting' for allowCancelPropertyValues. This means that the assistant can help with canceling, only if the activity type is 'troubleshooting'.
In this case, the cancel option is unavailable in the chat for activities other the 'troubleshooting' type of activity. This table provides the custom parameters and their predefined values:

Feature Oracle Digital Assistant Parameter Name Predefined Values Supported Oracle Field Service Property Type
Reschedule allowRescheduleProperty aworktype string/enum/int/field
allowReschedulePropertyValue ac_installation, furnace_repair, GS string/enum/int/field
Cancel

allowCancelProperty

aworktype string/enum/int/field

allowCancelPropertyValues

ac_installation, furnace_repair, GS string/enum/int/field
Send Message to Technician allowSaveMessageProperty aworktype string/enum/int/field
allowSaveMessagePropertyValues ac_installation, furnace_repair, GS string/enum/int/field
Share Feedback on external site allowExternalReviewProperty aworktype string/enum/int/field
allowExternalReviewPropertyValues ac_installation, furnace_repair, GS string/enum/int/field

To disable a feature, add 'N/A' for both the parameters. Oracle Digital Assistant doesn't allow empty values in custom parameters.

The Feedback feature does not have a configured option to switch. You can deselect it in the configuration on the Where is My Technician theme page.

Other parameters that the skill uses:

Feature Oracle Digital Assistant Parameter Name Predefined Values Description
All DAName Support assistant Name used when Oracle Digital Assistant introduces itself in the conversations with the user.
All dateFormat EEE d MMM Format of the dates used by the Skill when mentioning any dates in the conversations with the user. The format is based on this specification.
All endPoint Your Oracle Field Service REST API endpoint

You must configure the Oracle Field Service REST API endpoint to allow integration with an Oracle Field Service instance. For example

<OFS API endpoint>/rest

Cancel reasonDefaultValue DEFAULT The value that is set into the property configured for the "cancelReasonProperty" parameter, if the user doesn't provide a reason for cancellation.
Feedback maxNegativeThresh 3 Integer value that is used to treat the rating provided by the user as Negative, if the rating is equal to or less than the value of this parameter. If not, the value is treated as Positive.
authenticationServiceName authenticationServiceName WMTAssistantService Authentication service name provided at the time of configuring the service. Default value is given as an example.

Configure your Welcome Message

You can implement a welcome message in your ODA skill to avoid providing an empty chat window when the user clicks on the chat icon. Use a hidden message ‘Hi’ which is auto-generated by Where is My Technician and sent to ODA to imitate the first message by end-user.

The hidden message is not visible on the page and matches the user's first message. The hidden message is sent only once in the 'Where is my technician' session and it doesn’t matter whether the message is changed during the session or to which page ( Scheduled, Days before, On the way, Arrived or Feedback) it is sent. The message can be sent twice in the Feedback flow page. Refresh the browser page or open the 'Where is my technician' link on a new page to interrupt a session. If it is true, and the user opens the chat with the same 'Where is my technician' link, and a hidden message is sent again. You can configure the ODA skill with intents that can understand the message (that is, Hi) and perform actions.
  1. Add intent to your skill.

  2. Add some utterances and 'Hi' among them to the intent so that the 'Hi' message is understood.

  3. Initiate your intent in Dialog flow and set an action.

    metadata: Version: "1.0" main: true name: "YourName" context: variables: ... states: ... getIntent: component: "System.Intent" properties: variable: "iResult" transitions: actions: Greeting: "YourAction"
  4. Train your skill.

How to identify the hidden message sent by WMT
Since WMT sends different parameters used for Skill configuration in ODA, you must add a condition based on the 'activityId' value to the Dialog flow before OBotML part known as 'states' to identify the source of the hidden message (in our case, WMT).
metadata:
  Version: "1.0"
main: true
name: "YourName"
context:
  variables:
...
  checkActivityId:
    component: "System.ConditionEquals"
    properties:
      variable: "profile.activityId"
      value: "null"
    transitions:
      actions:
        equal: "NonWhereIsMyTechnician"
        notequal: "IntegrationWithWhereIsMyTechnician"
 
states:
...
 
  IntegrationWithWhereIsMyTechnician:
    component: "System.Output"
    properties:
      text: "Hi ${profile.customerName}! Your technician is ${profile.resourceName}"
      keepTurn: true
    transitions:
      next: "done"
 
  NonWhereIsMyTechnician:
    component: "System.Output"
    properties:
      text: "Hello! I am not Where Is My Technician assistant."
      keepTurn: true
    transitions:
      next: "done"
Chat Notifications to Users

The Where is My Technician page allows you to initiate a chat with end-users. A notification badge is shown on the chat icon to the end-users. You can develop ODA skill which can send messages to end-user to suggest any help with the order (additional order details, promo codes, etc.) or ask for the feedback (if a customer does not want to enable feedback for the Where is My Technician page and wants to implement their custom survey).

Example of chat initiation skill
Response:
  component: "System.Text"
  properties:
    prompt: "Hi, I'm your assistant. Do you need help with the appointment scheduled for ${activity.value.date.date?number_to_date?string[dateFormat]}?"

Validate the Integration

After you integrate Oracle Field Service with Oracle Digital Assistant, you must validate that the integration is working correctly. If your goal is only to get the integration with Where is My Technician working, you can skip validating in Oracle Digital Assistant. Use the procedure to validate in Oracle Digital Assistant for debugging purposes.

  1. To validate in Oracle Field Service and Where is My Technician, perform these steps after you configure the Where is My Technician theme and include the Message Scenarios:

    1. Initiate the change that triggers the message notification with a URL to Where is My Technician.

    2. Find the Where is My Technician URL (for example, from the email or the Messages tab of the Activity details) and navigate to it.

    3. On the Where is My Technician page, click the chat icon in the lower right corner.

    4. Notice the message sent by Oracle Field Service, with the options (skills) you have configured. You will not find the message if the integration is not successful.

  2. To validate in Oracle Digital Assistant:

    1. Create an activity and assign it to a technician.

    2. Add the Activity ID in the Skill's Custom Parameter "aid".

    3. Run "Skill Tester" (play button on the top right corner on the Skill's details page).

    4. Send a test message.

    5. Notice that the test message is received. You will not receive the message if the integration is not successful.

Assistant View for the Where is My Technician Page

You can change the default Where is My Technician theme or settings and apply the modified Where is My Technician theme to the Oracle Digital Assistant chat page. See Configure the Where is My Technician Theme.

Feedback Flow

The assistant opens automatically on the Where is My Technician page if the Oracle Digital Assistant and Feedback flow are enabled for a Theme and the Rating set up is configured for the Feedback page.

You can develop ODA skills to implement a custom feedback scenario on the Where is My Technician page based on the rating. You can implement the following feedback scenarios:
  • Give thanks for the good feedback.

  • Ask for confirmation to post their feedback on the company site.

  • Define a reason for the low score for a technician.

  • Suggest scheduling another follow up to handle an issue.

  • Connect a dispatcher to the chat to handle a situation directly.

Example of skill with positive and negative feedback
#Variable can be set as:
context:
  variables:
    rate: "string"
  setRate:
    component: "System.SetVariable"
    properties:
      variable: "rate"
      value: ${profile.rate}
 
#Example of how to switch depending on number of stars
completedActivityResponse:
 component: "System.Switch"
 properties:
 variable: "rate"
 source:
 values:
 - "1"
 - "2"
 - "3"
 - "4"
 - "5"
 transitions:
 actions:
 1: "negativefeedback"
 2: "negativefeedback"
 3: "negativefeedback"
 4: "positivefeedback"
 5: "positivefeedback"
#Positive feedback
positivefeedback:
    component: "System.CommonResponse"
    properties:
      metadata:
        responseItems:
          - type: "text"
            text: "Thank you for rating us high! Do you wish to provide additional feedback?"
            separateBubbles: true
            actions:
              - label: "Sure"
                type: "postback"
                payload:
                  action: "Agree"
              - label: "Nothing to add more"
                type: "postback"
                payload:
                  action: "SuccessBye"
#Negative feedback
 
 
  negativefeedback:
    component: "System.CommonResponse"
    properties:
      metadata:
        responseItems:
          - type: "text"
            text: "Thank you for your feedback. We are always looking to improve the way we do business with our customers. Do you willing to provide additional details?"
            separateBubbles: true
            actions:
              - label: "Problem remains unsolved"
                type: "postback"
                payload:
                  action: "unsolvedProblem"
              - label: "Service was unappropriate"
                type: "postback"
                payload:
                  action: "unappropriateService"
              - label: "Other"
                type: "postback"
                payload:
                  action: "system.textReceived"
                  variables:
                    system.text: "Other"
Migration Rules
If the Enable Oracle Digital Assistant check box is enabled and the Application ID field is set before the 20B release for the Where Is My Technician theme on the Configuration page, then these fields are available on the Theme Configuration page after you upgrade to Update 20B:
  • Application ID

  • Channel URI

  • Channel ID

You can set the new values of configured ODA channel in the Channel URI and Channel ID fields and delete the old Application ID value to apply the support of the Oracle Web Channel to the theme.

Custom Forms and Plug-Ins

From a business perspective, Forms are paper documents that Field Resources fill in, while performing their work. From Oracle Field Service perspective, a Form is a pre-configured page that can be configured using data elements that exist only in the context of a Form.

Features of Forms:
  • Administrators may create as many Forms as needed for the business.

  • Forms are not User Type specific; they are independent pages that are connected to User Types pages through links that are configured on context layouts.

  • After the Form is configured, all users see the same Form and capture the same data regardless of their User Type.

  • The Form Field data elements, which can be added to forms are not associated or “bound” to a specific field or custom property.

  • Forms are available only in Core Application, iOS and Android apps.

  • Contents of a submitted Form cannot be changed, even if a related entity or Form configuration changes later.

  • When a Form is submitted, all Form field elements, except those that have auto-calculated default values or values filled through predefined parameters are blank.

  • Forms don't support links to any types of pages such as standard actions, plug-ins, or other forms.

Forms are represented in three ways in Oracle Field Service:
  • A configuration page where all the required elements are added.

  • A page on a mobile device or a computer where technicians and dispatchers fill in data.

  • A submitted Form result that represents every sample of the completed Form. These results are available to users on separate pages and can be retrieved through APIs.

Provide Access to the Forms & Plugins Page

Users with access to the Forms & Plugins page can add and modify custom Forms and plug-ins.

  1. Click Configuration > User Types.

  2. Select the type of user for which you want to provide access.

  3. Go to the Screen configuration tab.

  4. In the Main menu tree, click Configuration.

  5. Click Click to Add and select the Forms & Plugins check box.

  6. Click OK.

  7. Click Forms & Plugins and then click Add new visibility.

  8. Select Read-write and click Save.

  9. Click Close.

    All the users of the selected User Type now have access to the Forms & Plugins page.

How a Form is Configured

Here are the high-level steps to configure a Form.

  1. Create the Form.

  2. Configure the Form elements.

  3. Add the Form to a page.

View the Forms and Plug-Ins in the Application

You can view the Forms & Plugins page to add a custom Form or a plug-in, and to export and import plug-ins.

  1. Click Configuration > Forms & Plugins.

    The Forms and Plugins page opens and displays the default plug-ins and the custom plug-ins and Forms. The page shows the number of action links that are configured for each Form and plug-in.
  2. To see the list of buttons configured for a Form or plug-in, click the number.

    A context menu appears and displays the buttons that are grouped by the context layout structure name in which it is configured. Within every context layout structure name, the buttons are grouped by the user type name. You can click a button to open the appropriate editor and navigate to the position on the editor. The button is also highlighted the button in the Visual Form Editor or Context Layout Editor.
  3. To add a new custom Form, click Add Form.

  4. To add a new plug-in, click Add Plugin.

  5. To export and import plug-ins, click Export Plugins and Import Plugins respectively.

  6. To search for a specific Form or a plug-in, click View and select the required options.

Create a Form

You create a Form so that Field Resources can fill it to capture statutory or business data required for an activity.

  1. Click Configuration > Forms & Plugins.

  2. Click Add Form.

    The Add Form dialog box appears.
  3. In the English field, add a name for the Form in English.

  4. Add the names in other required languages.

  5. In the Label field, add a label for the Form.

  6. Click OK.

    The Form is saved. The next step is to add elements to the Form.

Configure the Form Elements

After you create a Form, you must add elements to it. Form elements are the fields in which a Field Resource can display and capture the required data.

  1. Click Configuration > Forms & Plugins.

  2. Click the stack icon and click Modify content for the Form that you want to edit.

    The Visual Form Editor page appears and displays an accordion type panel with these options to help you add, edit, and search for elements:
    • Available elements: All the element types that you can use in this context are listed here. To add a new element, drag it from this section and drop it to the desired location on the form. You can also use the search option to search for an element within this section.

    • Data fields: All the data fields that you can use in this context across all element types are listed in this section. Drag an element from this section and drop it to the form, to add the data field with a pre-configured binding to the data source. You can also use the search option to search for a data field within this section.

    • Fields in this layout: All the fields you have used in the layout. Each field has an icon representing the GUI type of the element that is defined when you bind the field to a data source. The features of this section are:
      • Clicking an item scrolls the content to the appropriate item in the layout and highlights it without opening the context menu editor.

      • Clicking an item in the layout focuses the list to the appropriate item, if the panel is active (not collapsed).

      • If a field is present more then once in the content, you see a marker in a format (n / m). For example, (1 / 3) means first of the three occurrences. Clicking the marker takes you to the item on the layout.

      • The order in the list is according to the appearance on the configured form, top to bottom, left to right.

      • The search option lets you search for a field within this section.

    Another way to open this page is when you add the Form to a page. If you are configuring a page and there is a button that is configured to open a Form, then you can use the Modify Form content option. In this case, a new editor session is opened with the specified Form content. Ensure that you have saved all the changes to the page configuration before you click Modify Form content.
  3. Drag and drop the element that you want to add to the Form. For example, add a section, a text box, a check box, or a file element.

    Here are some special elements that you can add:
    • Form Field: Adds a field such as text box, list, check box and so on, to the Form. This type of fields exist on the Form only for presenting and gathering information. The data entered in Form fields will only be captured in a screenshot of the Form when the Form is Submitted. This data is not stored in the application. However, data for other fields and properties is captured as normal.

    • Barcode/QR Code Scanner: Adds an icon to the Form, using which users can scan a barcode or a QR code. The embedded scanning functionality (that is, camera) on the resource's mobile device is used to scan the code. The results of the scan is populated automatically in the associated field. This option is available as part of the Input element. You can add the Barcode/QR Code Scanner any number of times on a form. Before using the scan option, users must ensure that the Android and iOS app that is installed on their devices has access to the device’s camera. In Core Application, Barcode/QR scanner is displayed as a text box.
      Note: When you add multiple Barcode/QR code scanner check boxes on a form or page, ensure that the section contains only the Barcode/QR code scanner check boxes and Text elements. If the section contains any other type of element, the barcode scanner is not triggered.
    • Date and Time: Adds a date, time, or date and time field to the Form. The format of data in the data and time field is controlled by user settings. Specifically 'Time' (sudate_fid) and 'Date' (sudate_fid) user fields. The data captured from 'Date', 'Time', and 'DateTime' components is stored and exposed through the 'formSubmitted' event of Events API in a predefined format. Date and Time are form fields and not available for binding to a custom property. The formats are:
      • yyyy-mm-dd for 'Date'

      • HH:mm for 'Time'

      • yyyy-mm-dd HH:mm for 'DateTime'

      Integrators must convert data into other formats, if required.
    • Hidden value: Adds a field to:
      • Include calculated values, which are not required to be displayed when the Form is filled.

      • Include pre-populated values by open parameters. The values for these parameters are configured on the Form button. When the user opens the Form, these values are populated on the Form.

      • Use in other expressions, whose values will be included into the submitted Form data with the values of all other Form elements.

  4. In the Data binding section, bind the elements to appropriate entities and fields:

    1. Click the Form field drop-down list and select the entity and start entering the entity name that defines the data source.

      The application displays only those fields that contain the entered text in their label or caption.
    2. Select the field that you want to define as the data source.

      The application populates the Type field automatically, based on the field you select as the data source. If you do not bind your field to any entity, then you can use the text as a form field label.
    3. Optionally, click the pencil icon. In the Data field list, select the specific field that you want to associate with the selected element.

      If the Show only fields appropriate for element type check box is selected, only the fields that are appropriate for the selected entity and the element type are displayed. If the check box is not selected and a different type of field is selected, the element type is changed accordingly. For example, if your element type is Input and you select Activity Type [aworktype], then the element type is changed to the one that the Activity Type belongs to.
    4. Click OK.

  5. In the Visibility section, configure the visibility settings.

    1. To change the visibility, click Add new. In the Access mode section, select the required visibility.

    2. If you want to add any conditions to make the element visible, click the plus icon.

    3. Add the required condition and click Save.

    The visibility is Read-write (RW) by default.
  6. In the Translations section, add the labels for the field in the required languages.

    The number of languages in this section is same as the number of languages you have configured on the Configuration > Display page. The application adds a label by default and you can change it here. You can use this label in default expressions and in the visibility conditions of other Form items. Further, you can use this label to refer to the submitted values in APIs. Here is the screenshot that shows Form elements:
    This screenshot shows a Form being configured with the barcode, combo box, date, and text fields.
  7. Click Save on the Visual Form Editor page.

    The Form elements are saved. The next step is to add the Form to a context layout through a User Type page configuration.

Fields that Cannot have the Barcode/QR Code Scanner Option

You cannot have the Barcode/QR code scanner check box for these fields on the Visual Form Editor:

Activity fields

These auto-calculated fields:

  • Access Schedule [access_schedule]
  • Access Hours [access_hours]
  • Compliance Alerts [activity_compliance]
  • Alerts [activity_alerts]
  • SLA End [sla_window_end]
  • SLA Start [sla_window_start]
  • Traveling Time [travel]
  • Resource ID [pid]
  • Time Slot [time_slot]

These fields are not auto-calculated (but contain specific data):

  • Points [apoints]
  • Coordinate X [acoord_x]
  • Coordinate Y [acoord_y]
  • Duration [length]

These fields are not auto-calculated:

  • Name [cname]
  • Work Order [appt_number]
  • Cellular Phone [ccell]
  • Email [cemail]
  • Phone [cphone]
  • Account Number [customer_number]
  • State [cstate]
  • ZIP/Postal Code [czip]
  • City [ccity]
  • Address [caddress]

These auto-calculated fields:

  • First Manual Operation [first_manual_operation]
  • First Manual Operation Interface [first_manual_operation_interface]
  • First Manual Operation Performed by User [first_manual_operation_user_id]
  • First Manual Operation Performed by User (Login) [first_manual_operation_user_login]
  • First Manual Operation Performed by User (Name) [first_manual_operation_user_name]
  • Auto-Routed to Date [auto_routed_to_date]
  • Auto-Routed to Resource [auto_routed_to_provider_id]
  • Auto-Routed to Resource (Name) [auto_routed_to_provider_name]
  • Activity Time of Assignment [atime_of_assignment]
  • Activity Time of Booking [atime_of_booking]
  • Capacity Categories [activity_capacity_categories]
  • Coordinate Status [acoord_status]
  • Date [date]
  • Start - End [eta_end_time]
  • Delivery Window [delivery_window]
  • End [end_time]
  • Time Notified [time_delivered]
  • Work Zone [aworkzone]
  • Activity ID [aid]
  • Activity status [astatus]
  • Start [ETA]
  • Service Window [service_window] [service_window]
  • Travel estimation method [travel_estimation_method]

Inventory fields

These auto-calculated fields:

  • Changed Inventory ID [inv_change_invid]
  • Resource Id [inv_pid]
  • Activity Id [inv_aid]
  • Inventory Id [invid]
  • Inventory pool [invpool]

These fields are not auto-calculated (but contain specific data):

  • Quantity [quantity]

Resource fields

These auto-calculated fields:

  • ID [pid]
  • Working days left for reported data to start impacting duration estimations [skip_days_for_stats]
  • Reactivated [reactivated]
  • On-call Calendar [oncall_calendar]
  • Work Zones [resource_workzones]
  • Effective Work Skills [resource_effective_workskills]
  • Time slots [resource_time_slots]
  • Capacity Categories [resource_capacity_categories]
  • Work Skills [resource_workskills]
  • Calendar [calendar]
  • Queue status [queue_status]
  • Total [total]
  • Pending [pending]
  • Alerts [alerts]

These fields are not auto-calculated:

  • Name [pname]
  • External ID [external_id]
  • Email address [email]
  • Phone [pphone]

Service request fields

These auto-calculated fields:

  • Created [srcreated]
  • Activity [appt_ident]
  • Request Id [srid]
  • User Id [sr_uid]
  • Resource Id [sr_pid]
  • Activity Id [sr_aid]
  • Inventory Id [sr_invid]

These possibly auto-calculated fields:

  • User [uname]
  • Date [srdate]

User fields

These auto-calculated fields:

  • User ID [uid]
  • Registered [sucreated]
  • Failed login attempts [login_attempts]
  • Blocked to [login_blocked_to]
  • Last login [last_login]
  • Last password change [last_password_change]
  • Updated [suupdated]
  • Main Resource [main_resource_id]

These fields are not auto-calculated (but contain specific data):

  • Refresh Rate [refresh_rate]
  • Mobile Resource Count [mobile_provider_count]
  • Mobile Activity Count [mobile_activity_count]
  • Mobile Inventory Count [mobile_inventory_count]
  • Collaboration Group [collab_assigned_user_group]
  • Operator of Helpdesk [collab_operator_helpdesk]

These fields are not auto-calculated:

  • User name [uname]
  • Login [ulogin]
  • Password [password]

Where Can Forms Be Used

You can open Forms from these pages:
  • Activity details and Inventory details: You can open Forms from the links in the action bar and buttons inside the content.

  • Activity list, Inventory list, Forms history, User options, Print route: You can call Forms from the links in the action bar.

  • Dispatch console: You can open Forms from the links on the activity hint.

  • Pages containing resource tree: You can call Forms from the links on the resource hint.

  • Time view, List view: You can add Forms to the action menu.

Forms relate to the entities from which they are opened and submitted. In other words, if a Form is submitted in the context of an activity, then it remains connected to the activity. Users can view Form submission results from this specific activity. The same idea applies to inventory and resources contexts.
Note: You cannot add buttons to context layout structures that are responsible for changing the state of an activity, simultaneously with submitting data. Some of the context layout structures where you cannot add buttons are Add activity, Not done activity, Install inventory, and End activity. Further, you cannot remove or change the visibility of the two predefined buttons on these pages: Dismiss and Submit. This is to preserve the data integrity within transitions between states.

Add the Form to a Page

You add a Form to a context layout page, so that Field Resources can open and fill it.

  1. Click Configuration > User Types.

  2. Select the type of user for which you want to add the Form.

  3. Click Screen configuration.

  4. Find and click the page to which you want to add the Form.

    The Visual Form Editor page appears.
  5. Drag-and-drop the Button element to the section from where you want to invoke the Form.

  6. Click the button.

  7. In the Standard action screen field, click the pencil icon and then select Custom Forms.

  8. In the Screens list, select the name of the Form that you want to open and click OK.

    The label of the Form is displayed in the Custom Forms field, as shown in this screenshot:
    This screenshot shows a Form being added to the Edit/view activity context layout.
    By default all Forms have a visibility of Read-only.
  9. In the Visibility section, add the conditions based on which the Form is visible.

  10. In the Parameters section, add the values that you want the Form to be populated with:

    1. Click Add new.

      The Add parameter dialog box appears.
    2. Click Entity and select Form data.

      The Hidden value, Date, Time, and Date and Time elements added to the Form appear in the Field name list.
    3. Select an element in the Field name list.

    4. In the Value field, add the value that you want to be populated for the element.

      For example, let’s say you have a field by name City and you want to populate it with New York. Select City in the Filed name list and enter New York in the Value field. Whenever a Field Resource opens the Form, New York is populated for City. In another example, let’s say you want to populate today’s date in a Date field. Select the Date field in the Filed name list and enter ‘today’ in the Value field. Whenever a Field Resource opens the Form, today’s date is displayed. Similarly, enter ‘current time’ in the Value field to display the current time in the Time field.
    5. Click Save.

  11. In the Translations section, add a name for the Form.

    This name is displayed on the page from which the Form is invoked.
  12. Click Save on the Visual Form Editor page.

    The Form is added to the selected page.

View Form Submission Results

The Forms history page (Formerly 'Requests history') collects all the Form submission results. The Forms history page for an activity gives all the Form submissions for the activity. The Forms history page for an inventory item provides all the Forms submitted for an inventory item. Similarly, Forms history available from the Activity list and User options provides a list of Form submission results for a specific resource.

  1. Click Forms history for an activity, an inventory, or a resource.

  2. Click any record.

    The specific form is displayed with the values that were entered at the time of submission.

    When a user submits a Form, the application stores a snapshot of the values that the user has entered. The snapshot data remains unchanged, even if the corresponding entities and fields change later. In addition, except for the auto-calculated default values, or values filled through predefined parameters, the remaining field values are erased. Further, every time a user submits a Form, the application creates a formSubmitted type of event. You can retrieve the details of individual submissions by subscribing to this event. See the REST API guide for more information.

Lifecycle of a Form

From the time a user opens a Form on a mobile device to the time a Dispatcher views its submission results, a Form is viewed and processed in different ways.

The lifecycle of a Form is as described here:
  • A user opens a Form on a device.

    • All Form field elements, except those that have auto-calculated default values or values filled through predefined parameters are blank.

    • Form elements bound to fields and properties inherit their values.

  • The user fills in data and submits the Form.

  • Data is stored:

    • All submitted data is stored as a Form snapshot.

    • Values of fields and properties bound to page elements are populated and saved separately.

  • Data is available to customers:

    • On the user interface.

    • In an event of Events API.

    • As a Service request, if conditions match.

  • User goes to step 1 if there is a need to fill the Form again.

    • All Form field elements, except those that have auto-calculated default values or values filled through predefined parameters are blank.

    • Form elements bound to fields and properties inherit actual values.

Export and Import Forms

You export the contents of a Form, so that you can import it and create a similar Form. The best practice is to import the configuration (properties, activity types, resource types, inventory types, user types, and so on) before you export or import a form.

  1. Click Configuration > Forms & Plugins.

  2. Find the Form that you want to export.

  3. Click the stack icon and then click Export.

  4. Click Save and save the file the required location.

    The Form is saved in .json format.
  5. To import a Form:

    1. Click Add Form and add the Form details.

    2. Click the stack icon and then click Import.

    3. On the Import form content dialog, click Browse and select a .json file.

      The file is validated and the contents of the Form are saved.

Integrate with Other Applications

Your organization may have different software applications to take care of different business aspects. You can integrate those applications so that when an event occurs in one application, the appropriate changes are performed automatically in the other application. You can integrate applications in two ways: through Integration Cloud Service (ICS) and through REST APIs.

Integrating using ICS

When you use ICS, you create an integration point in Oracle Field Service. When an event occurs in Oracle Field Service, it is sent to the appropriate application through ICS. For example, a company in the manufacturing sector may have an ERP application to take care of their stocks. The company can integrate the ERP application with Oracle Field Service, so that when a field technician installs or deinstalls an equipment, the stock is updated in both, Oracle Field Service and the ERP application.

Integrating using REST APIs

Use REST APIs to integrate third-party applications such as mobile apps. To let a mobile app access REST APIs on behalf of a user, you use the OAuth 2.0 authentication. To use OAuth 2.0 authentication, you must register the client application with Oracle Field Service. Then, your client application requests an access token from Oracle Field Service or other external token service providers such as, Oracle Identity Cloud Service. The client application then sends the token to the API that you want to access.

Integrate with ICS

Your organization may have different software applications to take care of different business aspects. You can integrate those applications, so that when an event occurs in one application, the appropriate changes are performed automatically in the other application. For example, a company in the manufacturing sector may have an ERP application to take care of their stocks. The company can integrate the ERP application with Oracle Field Service, so that when a field technician installs or deinstalls an equipment, the stock is updated in both, Oracle Field Service and the ERP application. One of the ways with which you can integrate the applications is through Integration Cloud Service (ICS). When you use ICS, you create an integration point in Oracle Field Service. When an event occurs in Oracle Field Service, it is sent to the appropriate application through ICS.

Note: Configure this integration only if you want to send events or data from Oracle Field Service to ICS.
  1. Log in to Oracle Field Service.

  2. Click Configuration > Integration Cloud Service (ICS).

    The Integration Cloud Service (ICS) page appears.
  3. To add a new integration, follow these steps:

    1. Click Add new.

      The Add Integration Cloud Service (ICS) Access dialog box appears.
    2. Add a name or description for the application for which you are creating the integration in the End Point Label field.

      If you are using multiple instances of an application, such as Production and Testing, you can create multiple access points for the application.
    3. Add the host name of the application for which you are creating the integration in the ICS Domain field.

      For example, if the URL is “https://integration-a12345.integration.us2.oraclecloud.com/integration/flowsvc/ofsccloudadapter/NAME/v01/" then ICS Domain is: “integration-a12345.integration.us2.oraclecloud.com”.
    4. Add the user name of the ICS user in the ICS Username field.

      This user must exist in ICS and have permissions to access the integration endpoint.
    5. Add the password for the user name in the ICS Password and Confirm Password fields.

      The user name and the password are used to authenticate with ICS when Oracle Field Service starts sending events to ICS.
    6. Click Add.

      The integration details appear on the Integration Cloud Service (ICS) page. Next, you must log in to ICS to add the connection details and map the required fields.
  4. To modify an integration, follow these steps:

    1. On the Integration Cloud Service (ICS) page, click Modify for the end-point that you want to modify.

      The Edit Integration Cloud Service (ICS) Access dialog box appears.
    2. Edit the fields as required.

      You can edit all the fields, except for ICS Domain.
    3. Click Submit.

  5. To delete an integration, on the Integration Cloud Service (ICS) page, click Delete.

    The application stops sending events and updates to ICS.

Navigate to Internal Pages and Plug-Ins

You can directly access internal pages such as Activity details, List view, or Inventory details within the Oracle Field Service Mobile for Android or iOS apps or Core Application, using specific direct URLs.

Based on the page that is accessed and the user type accessing the page, you can send the following parameters with the URL:

Name Type Description Constraints

screen

String

Specifies the page that you want to access.

The following labels are supported:
  • activity_list

  • activity_by_id

  • start_activity

  • end_activity

  • cancel_activity

  • notdone_activity

  • suspend_activity

  • delay_activity

  • inventory_list

  • inventory_by_id

  • install_inventory

  • deinstall_inventory

date

Date

Specifies the date for the page that you want to access.

Date format is YYYY-MM-DD.

activityId

Number

Specifies the activity for the page that you want to access.

Valid activity ID is required.

resourceInternalId

Number

Specifies the resource for the page that you want to access.

A valid resourceInternalId is required.

Mandatory, if you are navigating from the Supervisor page.

inventoryId

Number

Specifies the inventory for the page that you want to access.

Valid Inventory ID is required.

The order of the parameters is not important. Also, any unsupported parameters are ignored. The supported parameters, URLs, and accessible pages might differ based on whether the logged-in user has access to other users (such as supervisor, technician). In case, there are missing or invalid params or if the user doesn't have access to the page, then an error message is displayed.

<OFS_CORE_APP_URL> is the URL to access the following OFS Core App pages:

Activity List

The activity_list label allows you to access the Activity List page.

Supported Parameters

Name Mandatory for Technician Mandatory for Supervisor

date

No

No

resourceInternalId

No

Yes

Possible URLs

URL Description Applicable for Technician Applicable for Supervisor

https://<OFS_CORE_APP_URL>/#screen=activity_list

Displays the Activity List page for today’s date.

Yes

No

https://<OFS_CORE_APP_URL>/#screen=activity_list&date=2020-02-19

Displays the Activity List page for the date, 2020-02-19.

Yes

No

https://<OFS_CORE_APP_URL>/#screen=activity_

list&resourceInternalId=3000001

Displays the Activity List page of the technician with resourceInternalId 3000001 for today’s date.

Yes

Yes

https://<OFS_CORE_APP_URL>/#screen=activity_list&date=2020-02-19&resourceInternalId=3000001

Displays the Activity List page of the technician with resourceInternalId 3000001 for the date, 2020-02-19.

Yes

Yes

Activity Details

The activity_by_id label allows you to access the Activity Details page.

Supported Parameters

Name Mandatory for Technician Mandatory for Supervisor

activityId

Yes

Yes

date

Yes

Yes

resourceInternalId

No

Yes

Possible URLs

URL Description Applicable for Technician Applicable for Supervisor

https://<OFS_CORE_APP_URL>/#screen=activity_by_id&activityId=4225435&date=2020-02-20

Displays the details for activity with id 4225435.

Yes

No

https://<OFS_CORE_APP_URL>/#screen=activity_by_id&activityId=4225435&date=2020-02-20&resourceInternalId=3000001

Displays the details for activity with id 4225435.

Yes

Yes

Constraints

  • The specified date must be the route date of the specified activity.

  • For technicians, the activity must be assigned to the technician.

  • For supervisors, the specified resourceInternalId must be assigned to the activity and the supervisor must have access to the technician.

Activity Actions

Page Label Description

start_activity

Access the Start Activity page.

end_activity

Access the End Activity page.

cancel_activity

Access the Cancel Activity page.

notdone_activity

Access the Not Done Activity page.

suspend_activity

Access the Suspend Activity page.

delay_activity

Access the Delay Activity page.

Supported Parameters

Name Mandatory for Technician Mandatory for Supervisor

activityId

yes

yes

date

yes

yes

resourceInternalId

No

yes

Possible URLs

URL Description Applicable for Technician Applicable for Supervisor

https://<OFS_CORE_APP_URL>/#screen=<SCREEN_LABEL>&activityId=4225435&date=2020-02-20

Displays the specified Activity Action page for the Activity ID, 4225435.

yes

No

https://<OFS_CORE_APP_URL>/#screen= <SCREEN_LABEL>&activityId=4225435&date=2020-02-20&resourceInternalId=3000001

Displays the specified activity action page for activity with id 4225435.

yes

yes

Constraints

  • The specified Activity Action page must be visible for the specified activity.

  • The specified date must be the route date of the specified activity.

  • For technicians, the activity must be assigned to the technician.

  • For supervisors, the specified resourceInternalId must be assigned to the activity and the supervisor must have access to the technician.

Inventory List

The inventory_list page label allows you to access the Inventory List page.

Supported Parameters

Name Mandatory for Technician Mandatory for Supervisor

activityId

No

No

date

No

No

resourceInternalId

No

yes

Possible URLs

URL Description Applicable for Technician Applicable for Supervisor

https://<OFS_CORE_APP_URL>/#screen=inventory_list

Displays the Inventory List page.

yes

No

https://<OFS_CORE_APP_URL>/#screen=inventory_list&activityId=4225435&date=2020-02-19

Displays the Inventory List page for the Activity ID, 4225435.

yes

No

https://<OFS_CORE_APP_URL>/#screen=inventory_list&resourceInternalId=3000001

Displays the Inventory List page of the technician with resourceInternalId, 3000001.

No

No

https://<OFS_CORE_APP_URL>/#screen=inventory_list&activityId=4225435&date=2020-02-19&resourceInternalId=3000001

Displays the Inventory List page for the Activity ID, 4225435. resourceInternalId is required for supervisors.

yes

No

Constraints
  • Inventory list action link should be visible from the activity.

  • The specified date must be the route date of the specified activity.

  • For technicians, the activity should be assigned to the technician.

  • For supervisors, the specified resourceInternalId must be assigned to the activity and the supervisor must have access to the technician.

Inventory Details

The inventory_by_id label allows you to access the Inventory Details page with the specified Inventory ID.

Supported Parameters

Name Mandatory for Technician Mandatory for Supervisor

inventoryId

yes

yes

activityId

No

No

date

No

No

resourceInternalId

No

yes

Possible URLs

URL Description Applicable for Technician Applicable for Supervisor

https://<OFS_CORE_APP_URL>/#screen=inventory_by_id&inventoryId=21229417

Displays the inventory details for the inventory ID, 21229417.

yes

No

https://<OFS_CORE_APP_URL>/#screen=inventory_by_id&inventoryId=21229417&activityId=4225435&date=2020-02-19

Displays the inventory details for the inventory ID, 21229417 and activity ID, 4225435.

No

No

https://<OFS_CORE_APP_URL>/#screen=inventory_by_id&inventoryId=21229417&resourceInternalId=3000001

Displays the inventory details for the inventory ID, 21229417 for the technician with resourceInternalId 3000001.

yes

yes

https://<OFS_CORE_APP_URL>/#screen=inventory_by_id&inventoryId=21229417&activityId=4225435

&date=2020-02-19&resourceInternalId=3000001

Displays the inventory details for the inventory ID, 21229417 and the activity ID, 4225435 for the technician with resourceInternalId 3000001.

yes

yes

Constraints

  • For technicians, the technician must have the inventory with the specified ID.

  • For supervisors, the specified resourceInternalId must belong to a technician with the inventory specified by inventory ID.

  • The specified date must be the route date of the specified activity.

  • For technicians, the activity must be assigned to the technician.

  • For supervisors, the specified resourceInternalId must be assigned to the activity and the supervisor must have access to the technician.

Inventory Actions

Page Label

Description

deinstall_inventory

Accesses the Add to Deinstalled page with the selected inventory.

install_inventory

Accesses the Add to Installed page with the selected inventory.

Supported Parameters

Name Mandatory for Technician Mandatory for Supervisor

inventoryId

yes

yes

activityId

yes

yes

date

yes

yes

resourceInternalId

no

yes

Possible URLs

URL Description Applicable for Technician Applicable for Supervisor

https://<OFS_CORE_APP_URL>/#screen=<SCREEN_LABEL>&activityId=4225435&date=2020-02-19&inventoryId=21229417

Displays the specified Activity Action page for the activity ID, 4225435 and for the inventory ID, 21229417.

yes

no

https://<OFS_CORE_APP_URL>/#screen= <SCREEN_LABEL>

&activityId=4225435&date=2020-02-19&resourceInternalId=3000001&inventoryId=21229417

Displays the specified Inventory Action page for the activity ID, 4225435 and inventory ID, 21229417.

no

yes

Constraints
  • The specified Inventory Action page must be visible for the specified activity and inventory.

  • For technicians, the technician must have the inventory with the specified ID.

  • For supervisors, the specified resourceInternalId must belong to a technician with the inventory specified by inventory ID.

  • The specified date must be the route date of the specified activity.

  • For technicians, the activity must be assigned to the technician.

  • For supervisors, the specified resourceInternalId must be assigned to the activity and the supervisor must have access to the technician.

Access to Custom Plug-Ins

You can directly access custom plug-ins within the Oracle Field Service Mobile Application for Android or iOS or the Core Application. You can access such pages from any custom Android or iOS app or through specific direct URLs.

Based on the page from where the plugin is accessed and the user type accessing the plugin, you can send the following parameters with the URL:

Name Type Description Constraints

plugin

String

Specifies the plugin to access.

The label must belong to a valid plugin. The plugin must be configured on one of the pages for the logged in user.

contextScreen

String

Specifies the context page from which the plugin is accessed.

The following Context Screen labels are supported:
  • activity_list

  • activity_by_id

  • inventory_list

  • inventory_by_id

Context pages have the same validations as page navigation. The order of the parameters is not important.

date

Date

Specifies the date for the context page.

Date format must be YYYY-MM-DD.

activityId

Number

Specifies the activity for the context page.

A valid Activity ID is required.

resourceInternalId

Number

Specifies the resource for the context page.

Must be a valid resourceInternalId. Mandatory if you access the ID from the Supervisor page.

inventoryId

Number

Specifies the inventory for the context page.

A valid Inventory ID is required.

Note:
  • External data: Except for the above parameters, all the passed parameters are sent to the plugin with the externalData key. If the same key is provided multiple times then the data is sent to the plugin as an array with the specified key.

  • Encoding data: If the data that you want to send has special characters then it must be URL encoded.

Passing Single Key Data
URL: https://<OFS_CORE_APP_URL>/#plugin=<PLUGIN_LABEL>&contextScreen=activity_list&speed=44.5&distance=11&model=V1
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "resource": {},
    "activityList": {
        "4225438": {
            "aid": "4225438"
        },
        "4225439": {
            "aid": "4225439"
        }
    },
    "inventoryList": {
        "21064417": {
            "invid": "21064417"
        },
        "21064418": {
            "invid": "21064418"
        }
    },
    "openParams": {},
    "externalData": {
        "speed": "44.5",
        "distance": "11",
        "model": "V1"
    }
}
Passing Array Data
URL: https://<OFS_CORE_APP_URL>/#plugin=<PLUGIN_LABEL>&contextScreen=activity_list&zipcodes=35801&zipcodes=06101&zipcodes=62701status=completed
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "resource": {},
    "activityList": {
        "4225438": {
            "aid": "4225438"
        },
        "4225439": {
            "aid": "4225439"
        }
    },
    "inventoryList": {
        "21064417": {
            "invid": "21064417"
        },
        "21064418": {
            "invid": "21064418"
        }
    },
    "openParams": {},
    "externalData": {
        "zipcodes": ["35801", "06101", "62701"],
        "status": "completed"
    }
}
Passing data with special characters
Original Data: "https://www.oracle.com/index?q=encoding"

Encoded Data: "https%3A%2F%2Fwww.oracle.com%2Findex%3Fq%3Dencoding"

URL: https://<OFS_CORE_APP_URL>/#plugin=<PLUGIN_LABEL>&contextScreen=activity_list&targetURL=https%3A%2F%2Fwww.oracle.com%2Findex%3Fq%3Dencoding
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "resource": {},
    "activityList": {
        "4225438": {
            "aid": "4225438"
        },
        "4225439": {
            "aid": "4225439"
        }
    },
    "inventoryList": {
        "21064417": {
            "invid": "21064417"
        },
        "21064418": {
            "invid": "21064418"
        }
    },
    "openParams": {},
    "externalData": {
        "targetURL": "https://www.oracle.com/index?q=encoding"
    }
}
Passing JSON Data
Original JSON String: {"street":"479 South Manor Station Drive","city":"Glenview","state":"IL","zipcode":"60025"}

Encoded JSON String: %7B%22street%22%3A%22479%20South%20Manor%20Station%20Drive%22%2C%22city%22%3A%22Glenview%22%2C%22state%22%3A%22IL%22%2C%22zipcode%22%3A%2260025%22%7D

URL: https://<OFS_CORE_APP_URL>/#plugin=<PLUGIN_LABEL>&contextScreen=activity_list&address=%7B%22street%22%3A%22479%20South%20Manor%20Station%20Drive%22%2C%22city%22%3A%22Glenview%22%2C%22state%22%3A%22IL%22%2C%22zipcode%22%3A%2260025%22%7D

{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "resource": {},
    "activityList": {
        "4225438": {
            "aid": "4225438"
        },
        "4225439": {
            "aid": "4225439"
        }
    },
    "inventoryList": {
        "21064417": {
            "invid": "21064417"
        },
        "21064418": {
            "invid": "21064418"
        }
    },
    "openParams": {},
    "externalData": {
        "address": "{\"street\":\"479 South Manor Station Drive\",\"city\":\"Glenview\",\"state\":\"IL\",\"zipcode\":\"60025\"}"
    }
}
Open Plugin from Activity List page
URL: https://<OFS_CORE_APP_URL>/#plugin=<PLUGIN_LABEL>&contextScreen=activity_list&serialNo=49126
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "resource": {},
    "activityList": {
        "4225438": {
            "aid": "4225438"
        },
        "4225439": {
            "aid": "4225439"
        }
    },
    "inventoryList": {
        "21064417": {
            "invid": "21064417"
        },
        "21064418": {
            "invid": "21064418"
        }
    },
    "openParams": {},
    "externalData": {
        "serialNo": "49126"
    }
}
Open Plugin from Activity Details page
URL: https://<OFS_CORE_APP_URL>/#plugin=<PLUGIN_LABEL>&contextScreen=activity_by_id&activityId=4225439&date=2020-02-27&serialNo=49126

{
    "apiVersion": 1,
    "method": "open",
    "entity": "activity",
    "resource": {},
    "activity": {
        "aid": "4225439"
    },
    "inventoryList": {
        "21064417": {
            "invid": "21064417"
        },
        "21064418": {
            "invid": "21064418"
        }
    },
    "openParams": {},
    "externalData": {
        "serialNo": "49126"
    }
}
Open Plugin from Inventory List page
URL: https://<OFS_CORE_APP_URL>/#plugin=<PLUGIN_LABEL>&contextScreen=activity_by_id&activityId=4225439&date=2020-02-27&serialNo=49126
{
    "apiVersion": 1,
    "method": "open",
    "entity": "inventoryList",
    "resource": {},
    "activityList": {
        "4225438": {
            "aid": "4225438"
        },
        "4225439": {
            "aid": "4225439"
        }
    },
    "inventoryList": {
        "21064417": {
            "invid": "21064417"
        },
        "21064418": {
            "invid": "21064418"
        }
    },
    "openParams": {},
    "externalData": {
        "serialNo": "49126"
    }
}
Open Plugin from Inventory Details page
URL: https://<OFS_CORE_APP_URL>/#plugin=<PLUGIN_LABEL>&contextScreen=inventory_by_id&inventoryId=21229417&serialNo=49126
{
    "apiVersion": 1,
    "method": "open",
    "entity": "inventory",
    "resource": {},
    "activityList": {
        "4225438": {
            "aid": "4225438"
        },
        "4225439": {
            "aid": "4225439"
        }
    },
    "inventory": {
        "invid": "21229417"
    },
    "openParams": {},
    "externalData": {
        "serialNo": "49126"
    }
}
Access OFS native app from other Android or iOS native apps

Accessing any of the URL formats and examples listed earlier from an Android or iOS device prompts you to open the link in a native app (if installed) or the web app using a browser.

However, if you don’t have the option to open the native app in the browser and you must open the OFS native app from another native app, then replace the link "https://<OFS_CORE_APP_URL>" with "com.oracle.OFS://", (everything else the same) in each of the above links.

Access to Pages and Plug-Ins in Offline Mode

To access the pages and plug-ins related to the activities of past or future dates, if the application (native app or web app) can access the specified activity in the Offline mode, then the links to inner pages also work for those activities.

Integrate with REST APIs

Oracle Field Service supports OAuth 2.0 authentication for API access. Use OAuth 2.0 authentication to let third-party applications such as a mobile app access REST APIs on behalf of a user. To use OAuth 2.0 authentication, you must register the client application with Oracle Field Service. Then, your client application requests an access token from Oracle Field Service or other external token service providers such as, Oracle Identity Cloud Service. The client application then sends the token to the API that you want to access.

Oracle Field Service supports these types of token service:
  • Oracle Field Service Token Service: The client application uses Oracle Field Service Token service to obtain an OAuth2 access token and authenticate with the APIs. Oracle Field Service token service supports two types of authentication:

    • Client Credentials: Authentication using client credentials is primarily used for back-end to back-end integration. For example, an application that requires pushing data to Oracle Field Service.

    • JWT Assertion: JWT assertion authentication can be used for back-end to back-end integration or for mobile applications. The Access Token generated using assertion flow may include the user identity, and Oracle Field Service performs actions as that user. The advantage of using assertion flow is that user's password is not shared with Oracle Field Service. When you use this type of authentication, the public key of the third-party application is imported into the Application entity and the third-party application can make API calls using its private key.

  • External Token Service: The client application uses an external token service such as Oracle Identity Cloud Service to obtain an OAuth 2.0 access token and authenticate with the APIs.

  • Oracle Identity Cloud Service: The client application uses Oracle Identity Cloud Service to obtain an OAuth 2.0 access token and authenticate with the REST APIs. You can upload the signing certificate for Oracle Identity Cloud Service and then configure Oracle Identity Cloud Service to issue OAuth2 Access Tokens. See the Oracle Identity Cloud Service documentation for information about where to get the signing certificate: https://docs.oracle.com/en/cloud/paas/identity-cloud/index.html.

Use these details to configure Oracle Identity Cloud Service:
  • Primary audience: <your Oracle Field Service instance name>. For example, ‘ofs-x1111'

  • Scope: The scope name must begin with a slash ( / ), followed by the application ID that you created in Oracle Field Service. For example, if the application ID is 'new_app' then the Scope is '/new_app'.

After filling in these details, note down the client_id and client_secret of the application.
Integrating applications using REST APIs includes these steps:
  1. Register the OAuth client application.

  2. Configure the authentication.

  3. Enable access to specific APIs for your application.

For more information about calling REST APIs from third-party applications, see the REST API for Field Service guide.

Create an Application

If you want to call REST or SOAP APIs from a third-party application, you must register the third-party application by adding it on the Application page in Oracle Field Service.

  1. Click Configuration > Applications.

    The Applications page appears.
  2. Click the plus icon, add these details, and then click Submit:

    Field Name Description
    Application Name Name of the third-party application that you want to register.
    Application ID A unique ID of the application.
  3. On the Applications page, click the application that you want to register on the left pane and complete these fields:

    Field Name Description
    Application general info section
    Application Name Name of the third-party application that you want to register. This field is populated automatically.
    Application ID A unique ID for the application. This field is populated automatically.
    Active Status of the Application. Inactive Applications don't authenticate or authorize anyone. When you make an active Application inactive, previously-issued access tokens don't work.
    Token Service Type of token service or identity provider the Application uses. Default is OFSC.
  4. Select the authentication service using these fields:

    Field name Description
    Authentication settings section
    Authenticate using Client ID/ Client Secret Select this check box to authenticate the application using client ID and client secret. Click Show Client ID/Client secret to view the client ID and client secret.
    Client ID The client ID for the third-party application. This ID is automatically generated.
    Client Secret/Show Secret The client secret for the third-party application. This information is automatically generated.
    Authenticate using JWT assertion Select this check box to authenticate the application using JWT assertion.
    Authenticate using external access token Select this check box to authenticate the application using an external access token. This field is displayed if you select External for Token service.
    Client Certificate/Upload The certificate signed by the private key of the Application. If this is absent, you cannot use OAuth2 JWT Assertion authentication. Click Upload to upload the certificate.
  5. Select specific APIs for your application using these fields:

    Field name Description
    API Access section
    Add new Click to add new APIs. The Add API access dialog appears. Select the APIs you want to add and click Submit.
    Available methods The list of the API methods available for the corresponding API. Click the menu to modify the fields or methods and to remove access to the API.
    Available entities The list of entities that the users of the current Application have access to. This option is available only for Core API and Metadata API fields.
    Available resource fields/ Available activity fields/ Available inventory fields/ Available service requests fields/ Available user fields The list of the fields available for the corresponding API. Clicking this opens the layout structure, where you can select the fields that the users of the current Application will be able to use to set or update using the API. This page functions as a context layout structure where the fields and their visibilities are set.
    Remove access Removes access to this API. Users that have access to this Application cannot use the corresponding APIs anymore.
  6. Add any access restrictions using these fields:

    Field name Description
    Additional restrictions section:
    Visible resources The resources that are visible to the Application. The Application performs actions only on the resource tree nodes that are included in this setting. If no resources are specified, the Application has access to entire resource tree. Click the pencil icon to select the resources that are visible to this Application.
    Allow access only for certain IP addresses The IP addresses that can access the current application. Add the IP address in the box.
    Allow Cross-origin resource sharing (CORS) from these web domains The white-list of domains from which you can make AJAX requests to Oracle Field Service REST API. Enter each domain name on a separate line. These rules apply:
    • The maximum length of a domain names is 253 characters.

    • The maximum number of domain names you can add is 100.

    • No leading or trailing white space must be present in a domain name.

    • Wildcards or special characters are not supported.

    • A single asterisk “*” indicates that all domains are allowed.

    • Domain names that are added or modified take a few minutes to be populated across the application.

    This table describes how the Visible resources field works:

    Visibility restrictions Behavior
    Empty When a user is authenticated on behalf of this Application, their location in the resource tree is used for visibility restrictions. The Application cannot authorize itself, it can only authorize users.
    Present When a user is authenticated on behalf of this Application, an intersection (not union) of their location in the resource tree and the application visibility restrictions are used for visibility restrictions.

Activity Booking

When a technician performs an activity at the customer's premises, the customer may enquire about the possibility to perform another job for them on a different day. The technician must be able to collect the information about the new job, create an activity, and schedule it right away. To book an activity, the technician must also have the ability to check the available capacity for that specific date and time. This situation is handled by the Activity Booking option. You must configure the activity booking context properly to get the most accurate and precise capacity calculation. The Book new activity option is configured in the Application screens section of the Screen Configuration page.

Note: The activity booking functionality, Quota management page, and the Capacity Area configuration functionality are available only with the "Oracle Field Service Enterprise Cloud Service" subscription.
Technicians can book activities in three ways:
  • Direct assignment booking
  • Quota based booking:
    • Time slot based
    • Booking interval based (or availability based)

Direct Assignment Booking

Activity booking uses the activity information and finds all the Capacity Areas that match the activity requirements. If a Capacity Area is configured for booking using direct assignment, the activity is created (or reassigned) in a technician’s route, provided the technician meets the activity requirements and has enough time to complete it. When there are many available resources that can work on the activity for a particular date and time slot, Oracle Field Service assigns the activity to one of them. The application typically finds a technician that has a smaller set of working skills than a technician with a wider skillset. This way, resource selection is optimized, so that the following activities that require booking have more available options. With this feature, technicians can control the booking strategy that is used on a Capacity Area level. Technicians can also configure different capacity areas to use different booking strategies.

Availability-Based Booking

Technicians can book activities for Capacity Areas with booking interval based quota configuration. They can use the booking interval based quota when the time slots overlap or, have a significant variation in the activity duration. When technicians choose the booking interval based quota, they must select the booking intervals on the Quota Configuration page. If they do not select the booking intervals, the application uses the default Capacity intervals that are configured on the Business Rules page.

When you configure a Capacity Area for booking using Quota (time slot based or availability based), then the activity is created (or reassigned) on the bucket that is associated with the Capacity Area. If there are multiple Capacity Areas, the technician must select a Capacity Area, select the day and time slot on which they want to perform the activity, and book it.

You can obtain the booking options from the application in two ways:
  • Through the Activity Booking page.
  • Through the new API function showBookingGrid. This API simplifies the process of integrating the Booking functionality with external applications.

Regardless of the method, the application uses the activity information you have entered and provides you the list of options where it may be booked.

As soon as you book an activity, Oracle Field Service subtracts the capacity required for its performance from the available capacity and adds it to the used capacity. It compares the used capacity to the quota values to make sure that orders for new activities are accepted only when the capacity is still available. Аs having capacity information up-to-date is crucial for the functionality, Activity Booking is available only in the online mode.

Prerequisites for Using the Activity Booking Feature

If you want to use the Activity Booking feature, you must complete these tasks:
  1. Configure the radius within which you want Oracle Field Service to consider the activities. You must configure the Nearby Radius field on the Business Rules page for this. Go to Configuration > Business Rules to specify the Nearby Radius value.
  2. Add the fields required for booking activities to the Book new activity Visual Form Editor. Typically, you need activity type, activity address, work skills for the activity, work zone it belongs to, activity duration, and the coordinates of the activity. On the Schedule booked activity Visual Form Editor, configure the fields that your technicians see when they reschedule an existing activity. Go to Configuration > User Types > Screen configuration > Book new activity (or Schedule booked activity) to add the fields.
  3. Add the Book (create) activity and Book (reschedule) activity buttons to the Edit/View activity and the Activity hint Visual Form Editors. Technicians use these buttons to book and reschedule activities. Go to Configuration > User Types > Screen configuration > Edit/View activity or Activity hint to add the buttons.
  4. Configure the Capacity Areas for booking activities. You can configure a different type of booking option for each Capacity Area. For more information, see the Using Capacity guide.
  5. Configure the booking recommendations. You can show or hide the booking recommendations for each Capacity Area separately. For more information, see the Using Capacity guide.

Create a Layout for Booking an Activity

Use the Book new activity option in the Application screens section of the Screen Configuration page to create a layout for booking an activity.

  1. Click Configuration > User Types.

  2. Select the user type for which you want to add a layout for booking a new activity.

  3. In the Access settings section of the General tab, select the Allow access via web application check box.

  4. Expand the Application screens section and click Book new activity.

    The Visual Form Editor opens.
  5. Drag-and-drop the fields that you want on the Book new activity page.

    You must have Activity type (aworktype) field. However, you cannot add file type of fields or properties, tabs, and the Time slot field.
  6. Select the visibility settings for all the fields.

  7. Click Submit.

    The layout is saved.
  8. Add the Book (create) activity button to the Edit/view activity Visual Form Editor:

    1. Expand the Application screens section and click Edit/view activity.

    2. Drag and drop the Button element.

    3. Click the element and then click the pencil icon in the Standard action screen field.

    4. Select Book (create) activity and click OK.

    5. Click Save.

      If you want technicians to reschedule existing activities, add the Book (reschedule) activity button.

Activity Type Constraints

The activity booking function applies a number of constraints on certain activity types.

Some activity types determine whether at all an activity can be booked, while others affect the configuration of different properties on the context. The list of activity types is available in the Activity Types page. Click Configuration > Activity Types to access the Activity Types page. Describe only those activity type constraints and conditions that apply equally to all the activity types that you want to be available for booking.

Include Time Slot Support

By default, activity types do not have the Support of time slots option selected. You must select the Support of time slots option for each activity type that is to be considered for booking.

  1. Click Configuration > Activity Types.

  2. On the Activity Types page, select the type of activity that you want to be considered for booking.

  3. Click Modify.

  4. Select Support of time slots, and then click Update.

Time Slot Page Configuration

The Schedule booked activity context defines the layout of the Time Slot page. While the time slot selection widget is pre-configured and cannot be changed, all other details of the booked activity can be specified in the Schedule booked activity context.

These restrictions apply to the context configuration:
  • You can add only read-only visibility condition for activities or properties on the context layout.

  • You cannot create tabs in the Schedule booked activity context.

Otherwise, there are no special constraints, as opposed to the Book new activity context. The Schedule booked activity context is available in the Application screens section of the Screen Configuration page.

Include the Calculate Travel Option

If you select the Calculate travel option for the activities to be booked, then the capacity calculation additionally considers all fields and properties defined in the Activity travel stats fields section of Statistics.

  1. Click Configuration > Activity Types.

  2. Click Modify against the activity type for which you want to add the option.

  3. Select the Calculate travel check box and then click Update.

    When you select this feature, you must add all the fields that you have selected for the Activity travel stats fields on the Statistics page to the Book new activity context layout and set the visibility as Mandatory.

Include the Calculate Activity Duration Using Statistics Option

If you select the Calculate activity duration using statistics option for the activities to be booked, then the capacity calculation additionally considers all fields and properties in the Activity duration stats fields selected on the Statistics page.

  1. Click Configuration > Activity Types.

  2. Click Modify against the activity type for which you want to add the option.

  3. Select the Calculate activity duration using statistics check box and then click Update.

    When you select this feature, you must add all the fields that you have selected for the Activity duration stats fields field on the Statistics page to the Book new activity context layout and set the visibility as Mandatory.

Enable Work Zone Support

You must enable Work Zone Support for booking activities. If you have enabled Work Zone Support at both, the company level and the activity level for the corresponding activity types, all fields from the work zone key are considered for capacity calculation.

  1. To enable Work Zone Support at the company level:

    1. Click Configuration > Business Rules.

    2. Select Work Zone support in the General section.

  2. To select this option at the activity level:

    1. Click Configuration > Activity Types.

    2. Click Modify against the type of activity that you want to be considered for booking.

    3. Select Support of work zones, and then click Update.

  3. Click Configuration > Work Zones and note down the field selected for Work Zone Key.

  4. Add this field with a Mandatory visibility in the Book new activity context layout.

Enable Work Skill Support

You must enable Work Skill Support for booking activities. If you have enabled Work Skill Support at both, the company level and the activity level for the corresponding activity types, all fields from the work skill conditions are considered for capacity calculation.

  1. To enable Work Skill Support at the company level:

    1. Click Configuration > Business Rules.

    2. Select Work Skill support in the General section.

  2. To select this option at the activity level:

    1. Click Configuration > Activity Types.

    2. Click Modify against the type of activity that you want to be considered for booking.

    3. Select Support of work skills, and then click Update.

  3. Click Configuration > Work Skills > Work skill conditions.

  4. Open the work skill that you want to be considered for booking and note down the work skill conditions.

  5. Add this field with a Mandatory visibility in the Book new activity context layout.

Activity Booking Error Messages

This section provides the list of possible errors and the corresponding messages the user may encounter while booking activities.

Missing Context Error

If at least one of the two contexts ('Book new activity', 'Schedule booked activity') is not added before using the Activity Booking functionality, the message: Form is misconfigured. Context layout missing appears. Depending on which context is missing, the error is shown so, you can access the corresponding pages.

Validation Errors

If any of the mandatory fields is empty on the booking activity contexts ('Book new activity', 'Schedule booked activity'), the validation message, Validation failed, please review your form is shown. If a time slot has not been selected on the Time Slot page, the activity is not booked and the message, Validation failed, please review your form. Time slot is not selected is displayed.

Capacity Calculation Errors

Capacity is not calculated in these cases:
  • Data entered in the previous step (creating booked activity) is insufficient.

  • A configuration has not been properly performed.

  • There is no available capacity that matches with the activity parameters.

The possible error messages that may occur at the capacity calculation stage, that is after submitting information entered in the booking activity form are as follows:
  • Work skills support is disabled at the company level.

  • Work skills are not supported by this type of activity.

  • Capacity category cannot be determined using the given activity fields.

  • The selected activity type is inactive.

  • Work zone cannot be determined by the given activity fields.

  • Field or property that is required for work zone 'location' value calculation is missing.

  • Time slots are not supported by this type of activity.

  • Field or property that is required for the duration estimation is missing.

  • Field or property required for travel estimation is missing.

  • The matching buckets found don't have the required quota for booking this activity.

  • Unable to find appropriate quota bucket for this activity.

Configure User Types

Use user types to manage permissions and restrictions for all users. You can create user types for your business that correspond to your existing business roles. Each user type has a profile that defines security and display permissions, such as the user’s login method, the ability to use certain functions, and access to menu items and properties. They may also include custom context layouts.

You assign each user exactly one user type. You can add or change user types at any time, and delete those which are no longer needed. You can also copy existing user type configurations to make new ones. This makes it easy to create multiple user types that share similar configuration settings.

For each page or function that you want to make available for a given user type, you set the visibility to Read-only or Read-write. If you don't define a visibility value, that page or function is hidden for that user type. Access to a page or tab automatically includes access to the actions on that page.

User-Type Settings

If your organization adds a new business role, you must create and configure a new user type for it. Similarly, if a business role is altered, you may have to modify the corresponding user type settings.

Changes to a user type assigned to Oracle Field Service Core Application users are applied shortly after they are saved on the User Types page. Changes to a user type assigned to Oracle Field Service Mobile for Android and iOS users are applied after the next synchronization.

User type settings fall into these categories, which appear as tabs:

  • General

    These basic settings define the user type options with respect to resource types and other users, as well as the user type access to the application and to its functions.

  • Screen configuration

    These settings define the pages, windows, context menus, and other elements visible to a certain user type and supports the context layout editor where the content, arrangement, and visibilities of each context are set.

  • Restrictions and Filters

    These settings define the restrictions on the activities and fields that are visible to the users of the current type.

General Tab

The first step in creating a user type is to define the general settings such as, user type name, access, and permissions.

This table describes the fields available on the General tab:

Setting Description Notes
User Type Info
Label A unique identifier of the user type. Required. No spaces are allowed.
Name A user-friendly name that describes the user type. Required. Spaces are allowed.
Active Indicates whether the user type is active. Activating a user type simply makes it assignable to users. Inactive user types still apply to users that are assigned to them.
Login Policy Defines the user authentication method to Oracle Field Service
Assigned resource types Shows the resource types available for this user type. To change the assigned resource types, click the pencil icon. You cannot remove a resource type if any users are currently assigned to this user type.
Can create users of these user types Lists the user types that this user type can create.

Inactive user types are greyed out and cannot be created by this user type.

Permission to create user types is reciprocal. For example, if user type Manager can create user type Dispatcher, user type Dispatcher can create user type Manager.

To change the user types this user type can create, click the pencil icon.

Can be created by users of following user types Lists the user types that can create the current user type.

Inactive user types are greyed out.

Permission to create user types is reciprocal. For example, if user type Manager can create user type Dispatcher, user type Dispatcher can create user type Manager.

Access Settings
Allow access to web application When enabled, users of the current type can use the unified Core Application to manage dispatch operations.
Allow access via installed application for Android When enabled, users can access the application through the Oracle Field Service Mobile for Android application.
Allow access via installed application for iOS When enabled, users can access the application through the Oracle Field Service Mobile for iOS application.
Permissions
Maps When enabled, the user can access the Map View on the Activities, Quota, and Resource Work Zones pages.
Use real-time traffic data When enabled, the check box, Show Traffic is shown on the Map view. Users can select the Show Traffic check box to view the current traffic data in the selected route. This option is not available for Contingent Workers (set as ‘Resource is a Contingent Worker’ parameter in Manage, under Configuration, and Resource Types).

The real-time update is available to users of Oracle Field Service Enterprise when Oracle Field Service Standard Map Cloud Service with Google Maps or Baidu Maps is part of your subscription.

Allow access to required inventory When enabled, the user is able to access the Required inventory functionality and perform all related actions. The Required Inventory permission for Manage is implemented as visibility for the Required Inventory tab in the Add activity or Activity details context.
Parts Catalog When enabled, the user can search for particular spare parts in the catalog using the standard search function.
Enable Smart Location alerts When enabled, the user can receive alerts on their mobile device whenever any compliance issues have occurred and have been identified by the SmartLocation module.
Enable GPS Telemetry When enabled, the user's geopositioning information can be collected directly from the user's device.
Disable route activation when geolocation is not enabled on device When selected, users cannot activate the route if they have not enabled the location settings on their device.
Limit location gathering to installed Android or iOS applications When selected, Oracle Field Service collects the location details only for the installed applications. If you don’t select this permission, the application collects the location details from all the interfaces that the field resource has logged in to. Be aware that even if you select this option, resource positions can still be sent through APIs.
Collaboration
Collaboration Select the check box to view the collaboration settings.
Allow inventory move via chat In addition to chat functions, allows the user to transfer inventory via chat.
Allow image sharing via chat In addition to chat functions, allows the user to share images via chat.
Allow activity move via chat In addition to chat functions, allows the user to transfer activities via chat.
Allow Video Call When enabled, the setting allows the user type to access the Video Chat functionality.
  • Requires a subscription to Oracle Field Service Enterprise.

  • If the resource type is a Contingent worker, then the Video Chat is not available even if the setting is selected.

Allow Video Call Feedback When enabled, a user can provide feedback for the Video Call service.
Activity Management
Allow activity move between resources When enabled, the user can move an activity from one resource to another
Allow activity move from non-scheduled pool to scheduled one When enabled, the user can convert a non-scheduled activity to one that is scheduled.
Allow access to non-scheduled pool When enabled, the user can access the pool of non-scheduled activities and perform actions to them.
Allow activity reorder inside the route When enabled, the user can change the position of an activity in the route.
Allow activity reschedule/move to non-scheduled pool When enabled, the user can move an activity to a different date or make it non-scheduled.
Allow activity deletion When enabled, the user can delete an activity together with canceling it. Otherwise, a canceled activity remains in the application.
Ignore work zones/work skills mismatch on activity move When enabled, the user can move activities to resources with work zones and/or work skills not matching those of the activity.
Allow repeating/mass activity creation When enabled, the user can create mass and repeating activities.
Set action time When enabled, the user can manually adjust the time of activity actions. Otherwise, the action time is logged as the current time.
Display the remaining Activity Time When enabled, the activity work progress countdown is displayed.
Allow next activity selection on Complete When enabled, the user completing an activity can select the next activity to start. Otherwise, only the next activity in the route can be started.
Display and allow adjustment of remaining Travel Time When enabled, the Travel Time Countdown is displayed and the user can adjust travel time. Available values are: 5, 10, 15, 30, 45 minutes, 1 hour, 1 hour and 30 minutes, 2, 3, 4 and 8 hours.
Suggest activity by location When enabled, displays the number of activities that are assigned in the same location for a technician. This information is displayed above the Start button on the Resource Info page. The distance within which a location falls is determined by the Resource is considered to be at the activity location if the distance to it is less than X meters setting in the SmartLocation/GPS section on the Business Rules page.
Resource Management
Allow changes in working calendar When enabled, the user can modify the working calendar of the resource.
Allow to move resources between Organization Units When enabled, the user can move the resources to different organizations in the resource tree.

Screen Configuration Tab

This table describes the fields available on the Screen Configuration tab:

Setting Description Notes
Application screens Includes the contexts used in the Core Application.
Collaboration and Identifiers Includes the contexts used in Collaboration and the entity identifier contexts.
Plugin API Includes the plug-ins used with activity, inventory, and resource properties. This context layout is deprecated with release 19A. Use the Forms & Plugins page to configure new plug-ins and migrate the existing plug-ins. When you finish migrating all the plug-ins, the Plugin API section will be removed.

Restrictions and Filters Tab

these table describes the fields available on the Restrictions and Filters tab:

Setting Description Notes
Hide all activities Determines if the users will or will not be able to access any activities in the system after a certain time. When enabled, the administrator also has to set the time after which the activities are to be hidden.
Hide activity fields Determines if the users will or will not be able to access certain activity fields after a certain time. The fields to be hidden are defined in the Field restrictions context accessible by clicking the Activity fields link. When enabled, the administrator also has to set the time after which the activity fields are to be hidden.
Filters restricting visible activities Defines whether the users of the current type will be able to view the entire routes or only some activities. Setting the visibility restrictions requires proper configuration of the applicable filters.

Screen Configuration Settings

Screen configuration settings define the page, dialog boxes, context menus and other elements visible to a certain user type. They also support the context layout editor, in which the content, arrangement, and visibilities of each context are set.

The Screen configuration tab contains the list of all contexts available in Oracle Field Service. All contexts are split into three sections that correspond to their location in the application:

  • Application screens: The contexts used in Core Application.

  • Collaboration and Identifiers: The contexts used in Oracle Field Service Collaboration Service and the entity identifier contexts.

The Screen configuration tab is active when the Allow access to web application option is selected for the user type. The same settings also influence the availability of the configuration sections. If the Allow access to web application option is deselected for the user type, the Application screens section is collapsed and inactive.

The list of settings is organized hierarchically and shows the relationships between different contexts. All context names are links to the context layout editor pages. This screenshot shows the Screen configuration tab:


This screenshot shows the Screen Configuration tab, which includes settings that are organized hierarchically and shows relationships between different contexts.
Note: Any settings configured in the Application screens section are retained if the Allow access to web application option is deselected afterward for the user type. If the access is allowed again, the same configuration settings apply again for the user type.

Links to new (not edited) or empty contexts are shown in red, while links to edited contexts are shown in blue. If you remove all elements from a context, its link color changes from blue to red to indicate that the context is now empty. If you create a user type without copying the settings of another user type, all contexts are shown in red. When configuring pages for a user type, the Context layout structure page provides an indicator to show that a property is configured. When you add an item to the Layout structure column of the page, it appears in red until you add visibility to the field. After you define a visibility for the item, it is no longer highlighted in the Layout structure column.

Note: You can add or remove the Collaboration Group and Operator of Helpdesk properties from the context layout structure of the Add/Edit User context for each user type. After you update the properties in the Add/Edit User context, select a user from the Resource Settings, Users page and click Modify to view the updated properties.

The hierarchy of contexts starts from the Main menu items context defining the main menu items available or unavailable for the current user type. The configuration of the Main menu items context defines the menu bar elements visible or hidden for a particular user type. Each menu bar element opens a certain page and, therefore, provides access to its functionality. If a certain page has been made available for a user type, all users of such type have access to the entire functionality implemented on that page. Similarly, if a page has been made unavailable for a user type, all users of such type cannot use the functionality implemented on that page.

Changing the visibility of the Message Scenarios menu item to Read-write allows the user to view and edit all elements of a message scenario. With the Read-only visibility, they can only view them. This screenshot shows the Settings tab of the View scenarios step, which was set as read-only in the Screen Configuration page:


This screenshot shows the Settings tab of the View scenarios step, which was set as read-only in the Screen Configuration page.
The links to contexts are connected with arrows showing the relation between the contexts. Hovering the mouse over an arrow highlights it in red for better visibility. This screenshot shows a highlighted arrow, which means you are hovering the mouse over that arrow:
This screenshot shows a highlighted arrow, which means you are hovering the mouse over that arrow.

Click a link to open the Context layout structure page and define the fields and actions of the context, and their visibilities for the user type. You can copy a context layout to another user type if the other user type uses the same or slightly modified layout of the same page or window. For this purpose, the Context layout structure page has the Copy to button, which opens the list of all user types in the application.

For the form type contexts, the link leads to the Visual Form Editor page, where you can edit context layouts in an easier and more transparent manner. You can delete the default Read/Write visibility on the sections and tabs in the Visual Form Editor. Additionally, Read/Write visibility is not added after migration. When the visibility condition for a property is mandatory and the property value is cleared, the value is set to null and the visibility is selected.

If you have shared the configuration for the current user type with one or more other user types, such user types are preselected in the Copy to list. If the user type selected in the list shares its configuration with other user types, such user types are automatically selected as well. The current context layout is applied to the selected user types. In this case it replaces the previous context layout settings, if any.

When a context layout is copied for another user type, only the current context is copied, while the rest of the configuration remains unchanged. When a context layout is copied, two separate identical context layouts are created. You can edit each layout independently without affecting the other one. However, if the destination configuration is shared with other user types, the current context layout is copied to all user types sharing the same configuration.

Context layout copying is confirmed with the message, Layout has been successfully copied. Closing the Context layout structure page returns the user to the User types page.

The Collaboration and Identifiers section contains the contexts falling under two groups:

  • Identifiers: Includes the identifier contexts for activity, inventory and service request

  • Collaboration: Includes all contexts related to the Collaboration module, as shown in this screenshot:


This screenshot shows the Collaboration and Identifiers section with its contexts and relations.
Note: Text formatting such as modifying the text size, bold/non-bold, italic, or coloring or properties is not supported.

Restrictions and Filters Page

The last step in creating a user type is to define whether you want to hide or show activities, activity fields, and activity filters.

This table describes the fields available on the Restrictions and Filters page:

Setting Description Notes
Hide all activities Determines whether the users can or cannot access any activities in the system after a certain time. When selected, the administrator also has to set the time after which the activities are to be hidden.
Hide activity fields Determines if the users can or cannot access certain activity fields after a certain time. The fields to be hidden are defined in the Field restrictions context. You can click the Activity fields link to access it. When selected, the administrator also has to set the time after which the activity fields are to be hidden.
Filters restricting visible activities Defines whether the users of the current type can view the entire routes or only some activities. Setting the visibility restrictions requires proper configuration of the applicable filters.

Copy or Share a Page Configuration

When you want to create a user type that is similar to an existing user type, you can use the Copy or share screen configuration option. When you use this option, you select a different source of the page configuration for the current user type. In this case the current user type is dissociated from the shared page configuration.

  1. Click Configuration > User Types.

  2. Select an existing user type, which you want to be based on another user type.

  3. Click Screen configuration > Copy or share screen configuration.

  4. Select one of these options:

    Option Action
    Use Screen configuration of {User Type} Select this option to share the page configuration with one or more user types. Only one set of configuration settings exists, and any changes of the page configuration of one of the user types causes similar changes of the page configuration of other user types. In this case, sharing is inherited. That is, if the user type selected for sharing has been sharing its page configuration with other user types, the same page configuration will be used for all of them. The note underneath advises the user about the user types sharing the same page configuration.
    Create Screen configuration as copy of {User Type} Select this option to copy the page configuration from another user type. In this case, two independent sets of settings are created, and any changes apply only to the user type for which they are made. The note underneath advises the user about the user type whose page configuration will be copied.
    Create empty Screen configuration Select this option to clear the current page configuration. Only the settings of the current user type are cleared. If the page configuration had been shared with or copied from another user type previously, it is disconnected and a new independent page configuration is created. The note underneath advises the user that only the page configuration of the current user type will be cleared.

    If you have created a user type as a copy of another user type and then shared the page configuration, the message, Screen configuration shared with: {User type} displays on the Screen configuration tab. When you share the page configuration with another user type, the same set of settings is used for both user types, and both user types refer to them simultaneously. A shared page configuration means that all context layouts and their visibilities are similar for all user types sharing them. If you modify the page configuration for one of the user types, the same changes are applied immediately to all other user types sharing it.

    If a user type has an independent page configuration, you can replace with another by sharing or copying the page configuration of another user type. All user types with page configurations not related to those of other user types have the Copy/share screen configuration link. This link leads to the same page configuration options as are offered for changing the current page configuration. However, as the current screen configuration is not used elsewhere in the system, selecting any option removes it permanently. The note warns the administrator that the current configuration will be lost.

Configure Header Icons

The application includes two distinct themes—a classic style and a modern style. The modern style theme is called Vanilla and it displays icons in the header region for the most frequently accessed pages. It has a menu to the left of the page, which provides access to the remaining pages. The classic style theme displays tabs with text. This screenshot shows the Vanilla theme user interface with the left pane, hamburger icon, and the header regions marked 1, 2, and 3 respectively:
This screenshot shows the Vanilla theme user interface.
This topic describes how to configure the header.

  1. Click Configuration > Themes..

  2. Click Set default in the Vanilla theme row.

  3. Click Configuration > User Types.

  4. Select the user type that you want to modify (you can also select the one that you are using). Click Screen configuration.

  5. Click Main menu items.

    The Context layout structure page appears.
  6. In the Dispatch section, reorder the menu items as required.

    The first item in the list becomes the Home page and gets the Home icon. The application displays only four icons before the ‘|’ marker, regardless of the number of items you place in the Dispatch section.
  7. Click Close and refresh the browser.

    The newly configured theme and the icons appear.

Configure the Main Menu

You can configure the main menu using the Main Menu context layout structure. The configuration affects the Supervisor view. The Manage, Maps, Calendars, and Resources menus are pre-configured for this layout and are available by default.

  1. Log in to the application.

  2. Click Configuration > User Types.

  3. Select a User Type for which you want to add the main menu. Click Screen configuration.

  4. Click Application screens > Main menu.

  5. Click the Click to add button and add any item that you want to display on the main menu.

    New layout items are available as Read-Only.
  6. Click X at the top-right corner.

  7. Sign out and sign in to the application.

    The newly configured main menu appears.

Edit the Context Layout Page

Use the Context Layout Structure to configure the fields that appear on the application pages.

  1. Click Configuration > User Types.

    The User Types page appears.
  2. In the left pane, select the user type for which you want to edit the context layout.

  3. Click Screen Configuration.

  4. Expand Application screens or Collaboration and Identifiers. For example, click Application screens.

  5. Click the page for which you want to edit the context layout. For example, click Activity hint.

    The Context layout structure for the selected page and the selected user type opens. On this page, you can add or edit properties, actions, tabs, columns, and sections. Properties appear as fields and actions appear as buttons. Tabs, columns, and sections define the structure of the layout. You can also configure visibilities to properties and define the conditions under which the visibility settings are effective.
  6. Follow these steps to add a property:

    1. Click the Click to add button.

      The Add property dialog box appears.
    2. Select the property that you want to add and click OK.

  7. Follow these steps to configure the visibility for the newly added property:

    1. Click Add new visibility.

      The [property name] visibility dialog box appears.
    2. Select the access mode.

    3. To add a condition for visibility, click Add new condition.

      The corresponding fields appear.
    4. Select a property, select the condition, select the additional condition if available, and then click the tick mark.

      For example, the condition can be equal, not in, empty, and so on. If you have selected the property as activity status and the condition as equal, the additional condition can be suspended and pending.
  8. Follow these steps to add an action:

    1. Click the Click to add button under Actions.

      The Add action dialog box appears.
    2. Select the action that you want to add and click OK.

      After adding the action, set visibility for it. Visibility is not set by default, so you must configure it for every field and action that you add.
  9. Follow these steps to add a tab:

    1. Click a property and click Group.

      The Add to group dialog box appears.
    2. Enter the name of the group.

    3. Select one of these options and then click OK:

      Option Description
      Section Select this option to start a new section or block.
      Tab Select this option to start a new tab with the name provided earlier.
      Predefined tab Select this option to include a predefined tab. Select the tab from the Tab type drop-down list. Predefined tabs are the tabs available in the application by default.
  10. Follow these steps to add a column or section:

    1. Select a property or an action and click Add marker.

    2. In the Add marker dialog, select End of column or End of section.

    3. Click OK.

Visual Form Editor

The Visual Form Editor is used to configure context layouts. After configuring a context layout, you must select the Allow access to web application check box for each user type to view the context in the application.

The Visual Form Editor includes an accordion type panel with these options to help you add, edit, and search for elements:
  • Available elements: All the element types that you can use in this context are listed here. To add a new element, drag it from this section and drop it to the desired location on the form. You can also use the search option to search for an element within this section. When you want a Button to set a custom enumeration field or property (that is, a combobox), you must ensure that the enumeration value is 'active'. You can set the enumeration property as active on the Modify Property page. For example: Let's say you want to set a value = '10' through a button for the 'Level' property. You must first configure the corresponding value = '10' in the parameters section of the corresponding Visual Form Editor. You must ensure that the enumeration value of '10' is active.

  • Data fields: All the data fields that you can use in this context across all element types are listed in this section. Drag an element from this section and drop it to the form, to add the data field with a pre-configured binding to the data source. You can also use the search option to search for a data field within this section.

  • Fields in this layout: All the fields you have used in the layout. Each field has an icon representing the GUI type of the element that is defined when you bind the field to a data source. The features of this section are:
    • Clicking an item scrolls the content to the appropriate item in the layout and highlights it without opening the context menu editor.

    • Clicking an item in the layout focuses the list to the appropriate item, if the panel is active (not collapsed).

    • If a field is present more then once in the content, you see a marker in a format (n / m). For example, (1 / 3) means first occurrence of 3 in total. Clicking the marker takes you to the item on the layout.

    • The order in the list is according to the appearance on the configured form, top to bottom, left to right.

    • The search option lets you search for a field within this section.

You can define Visibility settings for each object of the form. Values with identical visibility settings are grouped and the grouping happens after the settings are saved. Also, using the Translations section, you can translate the text that displays on each object to any of the supported languages. By default, the Visual form editor displays these elements:
  • Header: Displays the selected actions from the Actions object.

  • Footer: Contains the default Dismiss and Submit buttons for a form. You can only define visibility settings for the Submit button.

  • Submit and Dismiss buttons: Indicates the button that is visible for all forms.

Default Values and Validation Rules

You can configure string and integer fields to include default values and validation rules. This helps when your business needs some fields to be populated by default and some fields to be calculated automatically, based on the value of another field. Further, this function is allowed only for `string`, `int` and `enum` custom properties.

You can configure the fields and properties in these ways:
  • Add a default value: A default value is an auto-calculated value of a field or property. This value is based on certain business rules and is dependent on the values of other fields and properties. The default value is represented as formula filled in the corresponding configuration field. For example, when a property is filled with a specific value, another property is filled with the current date or time.

  • Add a validation rule: A validation rule is a restriction based on certain business rules and is dependent on the values of other fields and properties. A validation rule is represented as a formula filled in the corresponding configuration field. For example, the value entered for a property (property A) falls within a specific range (between values of property B and property C).

  • Use a formula for configuring the visibility and the value visibility: The formula is based on certain business rules and is dependent on the values of other fields and properties. The formula for the visibility of the field and its value must be filled in the corresponding configuration field. It's possible to transform an existing visibility configured through a constructor to a formula. The application uses this formula for calculating visibility as the primary path and visibility from the constructor as the secondary path.

Note:
  • If a default expression is configured with an empty value for a read-only field or property, it will NOT be hidden on the page. This means, the user will see the field or property name on the page, but it will not have any value.

  • For read-only fields, default values take priority over calculated values.

Auto-Generated and Auto-Calculated Fields
Auto-generated and auto-calculated fields can have a visibility of Read-Only. Regardless of the configured visibility, the application displays such fields as Read-Only. Further, such fields are not available for selection on the Context Layout Structure page of add pages such as, 'Add activity' and 'Add inventory'. The fields that can be set only as read-only are as given in this table:

Entity Field Description
ACTIVITY ETA Estimated time of arrival
acoord_status Coordinate status
acoord_x Coordinate X
acoord_y Coordinate Y
activity_alerts Activity alert
activity_capacity_categories Activity capacity categories
activity_compliance Activity compliance
activity_workskills Activity work skills
aid Activity ID
astatus Activity status
atravelarea Travel area
atype Activity Type
auto_routed_to_date Auto-routed to date
auto_routed_to_provider_id Auto-routed to Provider ID
auto_routed_to_provider_name Auto-routed to Provider name
aworkzone Work Zone
date Date
delivery_window Delivery window
end_time eta_end_time Estimated end time
first_manual_operation First manual operation
first_manual_operation_interface First manual operation (interface)
first_manual_operation_user_id First manual operation (user ID)
first_manual_operation_user_login First manual operation (login)
first_manual_operation_user_name First manual operation (user name)
service_window Service window
time_delivered Time of delivery
INVENTORY inv_aid Activity Id
inv_change_invid Changed Inventory ID
inv_pid Resource Id
invid Inventory Id
invpool Inventory pool
REQUIRED INVENTORY required_available_quantity Quantity in Resource Pool
required_model Model
required_quantity Quantity
required_type Type
SERVICE REQUEST appt_ident Activity
srcreated Created
srdate Date
srid Id Request Id
sr_aid Activity
sr_invid Inventory Id
sr_pid Resource Id
sr_uid User Id
uname User
RESOURCE alerts (always hidden)
calendar Calendar
oncall_calendar On-call calendar
pcapacity_bucket Capacity area
pending Pending activity
pid ID
pinitial_ratio Initial ratio for activity duration
p_rprid Routing profile ID
queue_status Queue status
reactivated Reactivated
resource_capacity_categories Capacity categories
resource_effective_workskills Effective work skills
resource_time_slots Time slots
resource_workskills Work skills
resource_workzones Work zones
skip_days_for_stats Working days left for reported data to start impacting duration estimation
total Total
pcolor (always hidden)
USER last_login Last login
last_password_change Last password change
login_attempts Login attempts
login_blocked_to Login blocked to
main_resource_id Main resource ID
mobile_activity_count Mobile activity count
mobile_inventory_count Mobile inventory count
mobile_provider_count Mobile provider count
show_placeholder_id Show placeholder ID
sucreated Registered
sustatus Status
suupdated Updated
uid User ID
Limitations
These limitations exist for default values and validation rules:
  • Work skills and work zones are not supported for default values and validation rules.

  • Custom properties with the "Geolocation element" GUI is not supported for default values and validation rules.

  • These limitations are applied to the configuration of expressions:
    • 2000 characters for configuring default values

    • 2000 characters for configuring validation rules

    • 4950 characters for configuring visibility as an expression

Supported Pages
You can configure default values and validation rules only on these Activity and Inventory pages:

Page Label
Edit/View activity mobile_activity_details
Cancel activity mobile_cancel_activity
Delay activity mobile_delay_activity
End activity mobile_end_activity
End prework mobile_end_prework
Not done activity mobile_notdone_activity
Add activity mobile_set_activity
Start activity mobile_start_activity
Start prework mobile_start_prework
Suspend activity mobile_suspend_activity
Add/Details inventory mobile_add_details_inventory
Deinstall inventory mobile_deinstall_inventory
Install inventory mobile_install_inventory
Send/View activity request mobile_activity_request
Add/View inventory request mobile_inventory_request
Add/View resource request mobile_provider_request
Edit Required Inventory mobile_add_edit_required_inventory
Supported Fields
You can configure default values and validation rules only on these fields:

Property name Property label Type Entity GUI
Account Number customer_number field activity text
Activity Type aworktype field activity combobox
Address caddress field activity text
Appointment Number appt_number field activity text
City ccity field activity text
Customer Email cemail field activity email
Customer Mobile Number ccell field activity phone
Customer Phone Number cphone field activity phone
Duration length field activity text
Inventory Type invtype field inventory combobox
Name cname field activity text
Points apoints field activity text
Quantity quantity field inventory text
Serial Number invsn field inventory text
Service Request Type srtype field service request combobox
State cstate field activity text
ZIP/Postal Code czip field activity text
Calculation Order
The result of a configured expression is calculated in this order:
  1. Value (Number, String, variable, function, expressing in round brackets)

  2. Special operators (BETWEEN, IN, CONTAINS)

  3. Unary operators (NOT, -)

  4. Multiplicative operators (*, /)

  5. Additive operators (+, -)

  6. Comparison operators (=, <>, <, >, <=, >=)

  7. Logical operator AND

  8. Logical operator OR

Configure Default Values and Validation Rules

When you configure fields on the Visual Form Editor, you can add a default value or a validation rule for fields and properties. You can also use formulas to configure visibility and visibility value.

  1. Click Configuration.

  2. Click User Types in the Users, Security, Integration section.

  3. Click Screen configuration.

  4. Expand the Application screens section and click the page that you want to modify.

  5. Select the field for which you want to add a default value or a validation rule. If the field is not added to the context layout, drag it from the left pane and drop it in the right pane.

    By default, the field is assigned with a visibility of Read-Write (RW).
  6. Follow these steps to change the default visibility:

    1. Click Add New in the Visibility section.

      The Visibility settings dialog appears.
    2. Select the required option in the Access mode section.

    3. If you want to change the visibility based on a condition, add it in the Conditions section.

      You can add a formula to determine the condition for visibility. The conditions entered here are given priority over the visibility inherited by the field or property.
      Note: When setting up the visibility for a specific property, you cannot create a visibility condition based on the property itself. For example, suppose that you want to set up the visibility of the property "City" as Read Write. You cannot set up a condition such as "City contains New York". Further, ensure that there are no circular dependencies. For example, the Customer Name field is displayed if the Customer Address field is filled and the Customer Address field is displayed if the Customer Name field is filled. Although the application does not display an error message when you configure such fields, the page on which the fields appear may not work properly.
    4. Click Show conditions as formula to view the conditions as a formula.

      These rules apply to showing conditions as formula:
      • If you click Show conditions as formula, the standard conditions constructor hides and a text area appears containing the auto-generated formula of the conditions.

      • If you don’t change the auto-generated formula, the formula is not saved. Show conditions as list is shown, so you can switch back.

      • If you change the formula and it differs from the auto-generated content, Show conditions as list is disabled.

      • If you change the formula and save the changes, the next time this dialog opens with the formula without the Show conditions as list link.

  7. Follow these steps to add a default value or a validation rule:

    1. Expand the Default value and validation section.

    2. Enter a value in the Default value field.

    3. Enter a validation for the value in the Validation field.

      You can use arithmetic operators, comparison operators, or functions to form the validation rule.
  8. Click Save.

    The details are saved and enforced when a user edits the corresponding page the next time.

Language Expressions

The language containing operators and functions is used for configuring default values, validation rules, and visibility of fields and properties.

The language is described in this table:

Argument Description Usage Pattern Use in
Default rules Validation rules Visibility
Variables, entities, and properties
this Value of current element this > 100 No Yes No
entity.property entity.`label` Value of property of entity. Use for wrapping labels with spaces. activity.aworktype = 1 Yes Yes Yes
White spaces and comments
[space], [tab], [line break] Assuming multiple white spaces as single space. Assuming white space as separator. this + 100 Yes Yes Yes
/* Any comment */ Assuming comment block as single white space. activity.PROP_A1 > 77 /* 77 - is predefined parameter */ Yes Yes Yes
Logical operators (case sensitive, operands will be converted to Boolean)
OR Logical disjunction a OR b Yes Yes Yes
AND Logical conjunction a AND b Yes Yes Yes
Unary operators
NOT Logical not (operand will be converted to Boolean) NOT (a AND b) Yes Yes Yes
Arithmetic inversion (operand will be converted to Number) - activity.PROP_A1

this * (- activity.PROP_A2)

Yes Yes Yes
Equal Comparison Operators (case sensitive for Strings). Operands will be converted to String
= Equal to a = b Yes Yes Yes
<> Not equal a <> b Yes Yes Yes
Comparison Operators (case sensitive for Strings). Use toNumber() for arguments if number comparison is needed.
< Less than a < b Yes Yes Yes
> Greater than a > b Yes Yes Yes
<= Less than or equal to a <= b Yes Yes Yes
>= Greater than or equal to a >= b Yes Yes Yes
Arithmetic Operators (all operands will be converted to Number, any arithmetic operation with Infinity/NaN returns Infinity/NaN)
+ Addition a + b Yes Yes Yes
- Subtraction a — b Yes Yes Yes
* Multiplication a * b Yes Yes Yes
/ Division

Division by zero: Division by zero returns infinity, which will be converted to "" (empty string).

a / b Yes Yes Yes
Additional Operators (case sensitive)
string CONTAINS needle Return true if `string` contains `needle` (operands will be converted to String) this CONTAINS "A0"

activity.PROP_A1 CONTAINS concat("-", this)

NOT activity.PROP_A2 CONTAINS activity.PROP_A3

Yes Yes Yes
value IN (value1[, value2, [, valueN]]) maximum 1000 arguments Returns true if `value` is equal to any `value1`...`valueN` (value will be converted to String) this IN (1, 2, 3, 4)

activity.PROP_A1 IN ("value1", "value2")

NOT activity.PROP_A2 IN ("value1")

Yes Yes Yes
value BETWEEN (min, max) Returns true if `value` is equal to `min`, equal to `max` or between them. The same as: value >= min AND value <= max (operands will be converted to Number) 1 BETWEEN (0, 100)

NOT 200 BETWEEN (99, 100)

Yes Yes Yes
Functions (case sensitive)
if(condition, value1, value2) Function which returns value1 argument if condition is true and value2 argument if condition is false (condition will be converted to Boolean) if(activity.PROP_A1 > 0, 1, 0) Yes No No
now(string) Returns current date in required format. View corresponding section for details now("yyyy-MM-dd HH:mm:ss") Yes No No
toNumber(value) Formatting object to required number format toNumber(activity.PROP_A1)

toNumber("123.45")

Yes Yes Yes
toString(value) Formatting object to string toString(activity.PROP_A1)

toString(123.45)

Yes Yes Yes
concat(string1, string2 [... ,stringN]]) maximum 20 arguments Concatenate strings (all operands will be converted to String) concat(this, "#", activity.PROP_A1) Yes Yes Yes
toLowerCase(string) String to lower case (operand will be converted to String) toLowerCase(activity.PROP_A1) Yes Yes Yes
toUpperCase(string) String to upper case (operand will be converted to String) toUpperCase(activity.PROP_A1) Yes Yes Yes
empty(value) Returns true if `value` is undefined or empty string or NaN or Boolean, false in all other cases empty(activity.PROP_A1)

NOT empty(activity.PROP_A2)

Yes Yes Yes

Data Type Conversion

This table describes the types of data used for validation rules and the way the application converts them:

Number String Boolean NaN Infinity Undefined
Number NA 123 = “123”

1.5 >= “1.5”

1 = True

0 = True

-10 = True

NA NA NA
String “ ” — 0

“1asda” = 0

“1.5” = 1.5

“2,3” = 0

NA “ ” = False

”anything” = True

“0” = True

“False” = True

NA NA NA
Boolean True = 1

False = 0

True = “True”

False = “ ”

NA NA NA NA
NaN NaN “ ” False NA NA NA
Infinity Infinity “ ” False NA NA NA
Undefined 0 “ ” False NA NA NA

Examples of Validation Rules

Scenario 1: Report Gas Consumption

Let's say an activity contains information about gas consumption. There are three of types of consumption: predicted, actual, and removed. The 'predicted' amount of consumed gas is saved in the activity. When a Field Technician chooses to report the actual information about the consumed gas, then the difference between 'actual' and 'predicted' data must be calculated automatically. If the actual consumption exceeds the predicted consumption by more than 20 cubic meters and the conditions of the gas counter are good, then the 'Reporting notes' property is displayed.

Prerequisites: Let us assume that 'Predicted gas consumption', 'Actual gas consumption', 'Difference', 'Counter is not broken' and 'Reporting notes' string-type properties are configured in the application. And, there is the 'Counter is not broken' integer property with a check box on the GUI.

Configuration: Configure the expressions in the 'Default' field for the 'Difference' property. For example: activity.real_consumption-activity.predicted_consumption

Visibility: Set the visibility for 'Reporting notes' as Read/Write with the same formula as the condition: (activity.real_consumption-activity.predicted_consumption) >20 AND activity.counter_conditions=1

Scenario 2: Checking Ratio

A Field Technician has to enter the Upstream Signal-to-Noise ratio to complete an activity (it is mandatory). The range must not be seen and it has to be anywhere between +32 to 52 dBmV. When the Field Technician enters a value of 55dBmV, which is not in the range then the Field Technician must know that is not the range and has to try again. The Field Technician measures again and enters 51dBmV, which is in the range allowing to complete the activity.

Prerequisites: Let's assume that the Upstream Signal-to-Noise' property is configured in the application. The 'Upstream Signal-to-Noise' property is configured on the 'Complete activity' page as mandatory.

Configuration: Configure the expression in the 'Validation' field for the 'Upstream Signal-to-Noise' property. For example: this BETWEEN (32,52).

Configure the custom error message in the corresponding field to be displayed to the techician.

Processing Rules

This topic describes the rules based on which default values and validation rules are calculated.

Default value rules

For read-only fields and properties:
  • Default value is always calculated for empty fields and properties.

  • Default value is not calculated for not-empty fields and properties.

  • Default value is recalculated every time a dependent field is changed, where dependent fields are fields used in the formula of the rule.

For read-write or mandatory fields and properties:
  • Default value is always calculated for empty fields and properties.

  • Default value is not calculated for not-empty fields and properties.

  • Default value is recalculated every time a dependent field is changed, when the dependent fields are used in the formula of the rule.

  • Default value stops calculated once it's manually changed on the open form.

  • Default value stops calculated once it's submitted with not-empty value.

  • Default value is not calculated for fields and properties with pre-filled values defined on the Properties configuration page.

Validation rules

For read-only fields and properties: Not applicable to read-only fields

For read-write fields and properties:
  • Are used for read-write fields and properties.

  • If a value of certain field or property does not match with the configured validation rule, then the form can be submitted.

For Mandatory fields and properties:
  • Are applicable to mandatory fields and properties.

  • If a value of certain field or property does not match with the configured validation rule, then the form cannot be submitted.

  • For fields and properties where validation rules are not configured, the 'NOT empty' rule is automatically applied (current logic).

  • For fields and properties where validation rules are configured, the system uses that rules on the submission of the form. That is, if a validation rule states that a mandatory field 'IS empty' then it will be submitted without value.

Conflict Resolution
If a configured visibility rule contradicts with a configured default value, these rules are applied to resolve the conflict:
  • for read-only fields and properties, the form is submitted and warning a message is displayed

  • for mandatory fields and properties, the form is not submitted and an error message is displayed

Syntax for Default Values and Validation Rules

This topic describes the syntax to configure the default values and validation rules.

Naming of entities: Use these names to relate custom properties and product fields to required entities:
  • activity - prefix for activity properties/fields. Example: activity.PROP_A1

  • inventory - prefix for inventory properties/fields. Example: inventory.PROP_I1

  • resource - prefix for resource properties/fields. Example: resource.PROP_R1

  • user - prefix for user properties/fields. Example: user.PROP_U1

  • request - prefix for service request properties/fields. Example: sr.PROP_SR1

Operators: All operators are case sensitive and must be used in the configuration as described in the "Language expression" section. Examples:
  • activity.PROP_A1 = 100 OR activity.PROP_A1 = 200 - is correct

  • activity.PROP_A1 = 100 or activity.PROP_A1 = 200 - is incorrect

Numbers and Strings: String-type values must be used in expressions in double or single quotes. For example:
  • "string expression"

  • "12345"

  • 'single'

Escape sequences: The allowed string escape sequences are:
  • \' – To escape ‘ within single quoted string

  • \" – To escape “ within double quoted string

  • \\ – To escape the backslash

  • \n – To add line breaks between string

  • \t – To add tab space

To ignore other escape sequences:
  • \radasd => radasd

  • \x123 => x123

To use integers in expressions, use them without of quotes. For example:
  • 12345

  • 6

Use float numbers with a dot as delimiter and without quotes. For example: 2.86954.

Properties and Fields

For properties and fields, the entity is given first followed by the label, and separated by a dot. If the label contains anything other than a to z, A to Z, 0 to 9, or underscore, wrap it with backticks. Examples:
  • activity.PROP_A1 = 25

  • activity.PROP_A1 <> activity.PROP_A2

  • inventory.`LABEL WITH SPACE`

Functions in Language Expressions

Use functions in expressions in the format where the function's name is given first followed by the expression in brackets. Separate arguments by comma. All functions are case sensitive and must be used in the configuration as described in the "Language expression" topic.

Examples for functions are:
  • toNumber("string expression")

  • if(activity.PROP_A1 > 10, 15, activity.PROP_A2 + 200)

  • toLowerCase(activity.PROP_A1) - is correct

  • tolowercase(activity.PROP_A1) - is incorrect

‘if’ function

The function consists of three attributes separated by comma. The function represents this logic: if attribute 1 is <some value> then set <some value> else set <other value>. Example: if (activity.PROP_A1 > 0,15, activity.PROP_A2+200)

`now` function
The function can be set as now("format") where the format can be DATE, DATETIME, TIMESTAMP. Include the value of the format between double quotes, similar to strings. Examples:
  • DATE - now("yyyy/MM/dd")

  • DATETIME - now("yyyy/MM/dd hh:mm:ss tt")

  • TIME - now("HH:mm:ss")

`toNumber` and `toString` functions
The rules described in the "Numbers and Strings" and "Properties and Fields" sections are applicable to the toNumber and toString functions. Examples:
  • toNumber("12345")

  • toNumber(activity.PROP_A1)

  • toString(1245)

  • toString(activity.PROP_A2)

'concat' function
The function can contain any number of operands separated by comma and placed in between brackets. Examples:
  • concat("abc", 15,"cde")

  • concat(activity.PROP_A1,activity_PROP_A2)

`toLowerCase` and `toUpperCase` functions
The functions are used to convert strings to lower or upper case. The functions contain only one operand placed in brackets. Examples:
  • toLowerCase("ABCD")

  • toLowerCase(activity.PROP_A1)

  • toUpperCase("abcd")

  • toUpperCase(activity.PROP_A1)

'empty' function
The function can be set with some field or property defined in brackets followed by the function. Examples:
  • empty(activity.PROP_A1)

  • if(empty(activity.PROP_A1),1000,activity.PROP_A2 +200)

  • NOT empty(activity.PROP_A1)

Activity type groups
You can configure a group of activity types for default values, validation rules, and visibility fields and properties. It is configured in the format of activity.awortype_group = "LABEL", where the value defining a label of an activity type group is included in double or single quotes. Examples:
  • activity.awortype_group = "internal"

  • activity.aworktype_group IN ('customer', 'maintenance')

The now Function

The 'now' function returns the date and time in the resource time zone.

You can configure the function according to the format given in this table:

Format Character Description Example
d Day of the month, 2 digits 1 to 31
dd Day of the month, 2 digits, with leading zeros 01 to 31
H 24-hour format of an hour 0 through 23
h 12-hour format of an hour 1 through 12
HH 24-hour format of an hour, with leading zeros 00 through 23
hh 12-hour format of an hour, with leading zeros 01 through 12
M Numeric representation of a month 1 through 12
m Minutes 0 to 59
MM Numeric representation of a month, with leading zeros