3Configure and Use Plug-Ins

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 with Oracle Field Service Mobility Cloud Service. 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 with Mobility Cloud Service.
    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. The following 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 Mobility Cloud 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.

Configure a Plug-In to Add to the Main Menu

You can add plug-ins that are created as HTML5 applications to the Main menu. You cannot add native application plug-ins.

  1. Click Configuration > Forms & Plugins.

  2. Click Add Plugin.

  3. Complete these fields on the Add Plugin page:

    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. Select HTML5 application.

    This means, the plug-in uses an external application to extend the functionality. The HTML5 plugin is 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. Clear this check box.

    When you do not use the Plug-In API, the URL is opened in a new tab, window, or 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). 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. You can use only User entity fields as placeholders.
    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 with Oracle Field Service Mobility Cloud Service.
    Open in iframe Determines whether the plug-in uses the iframe layout. If you clear the field, the plug-in’s URL is opened in a new browser tab or window.
  4. Click Save.

    If you set the external plug-in as the first item on the Main menu context layout, the menu item is displayed in the correct order. However, the plug-in does not open when a user logs in to the application. Instead, a standard page or a plug-in that you have created using the Plugin API Framework that is next in the order is opened.

Available Placeholders for POST Data for Main Menu Plug-Ins

You can use only User entity fields as placeholders for the POST data and URL.

Here are the fields that you can use as placeholders:

Placeholder User Property
allow_desktop_notifications Popup Notification
allow_vibration Vibration
design_theme Design Theme
main_resource_id Main Resource
mobile_activity_count Mobile Activity Count
mobile_inventory_count Mobile Inventory Count
mobile_provider_count Mobile Resource Count
sudate_fid Date Format
sulong_date_fid Long Date Format
sustatus Status
sutime_fid Time Format
su_zid Time zone
uid User ID
ulanguage Language
ulogin Login
uname User
uname User Name
user_type_id User Type

Some of these properties are available only if you add them to an application page, either directly or through a button for a Form for which you have configured these fields.

Change the Plug-In Tile Appearance

Use the iconData parameter to change the appearance of the plug-in button on the Landing page. You can change the status text, icon image, and color of the plug-in button. The status you can show includes number of processed activities, status of the order, number of pending actions, and so on. When the data is synchronized successfully, you can even change the icon to indicate it.

  1. Determine the data that you want to display or update and the message through which you want to update.

  2. Send the information that you want to display or update, in the iconData parameter.

    iconData is available for close, initEnd, and sleep messages. The data is applied real time. That is, if the plug-in is woken up when the user is on the Landing page, the icon is updated immediately after the plug-in sends the iconData parameter in the sleep message. The iconData parameter includes these fields:

    Field Type Limits Description
    color String One of:
    • "default"

    • "highlight"

    If the value is set to "highlight", the plug-in's button on the Landing page changes its color to get the user's attention.
    image Blob
    • Max size: 64 KiB

    • Allowed types:
      • image/svg+xml

      • image/png

    Icon picture. It's recommended to use a scalable monochrome white icon in SVG format.

    If the bitmap picture is in PNG format, it must not be smaller than 64x64 px.

    text String Max length: 3 chars The short text that is shown as large title on the plug-in's button. May contain both letters and digits.
Example of the close Message:
{
var closeData = {
    "apiVersion": 1,
    "method": "close",
    "iconData": {
        "color": "highlight",
        "text": "117",
        "image": new Blob([
            '<?xml version="1.0"?>' +
            '<svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" viewBox="0 0 64 64">' +
                '<rect x="16" y="16" width="32" height="32" fill="#fff" />' +
            '</svg>'
        ], { type: 'image/svg+xml' });
    }
}
 
 
window.parent.postMessage(closeData, origin);   
}

 

Placeholders in the URL

You can use several placeholders in the plug-in’s URL. The placeholders are replaced with the values of the corresponding properties and are processed by the server that hosts the plug-in

This table describes the placeholders.

Placeholder Description
{user_id}, {uid} ID of current user
{date} current date
{timestamp} current timestamp in ISO format
{uname} User name
{ulanguage} ID of user language
{ulogin} User login
{su_zid} User timezone
{allow_desktop_notifications} Parameter defining whether the user allows HTML5 notifications
{allow_vibration} Parameter defining whether the user allows vibration alerts

Authentication

You can use the HTTP Basic or HMAC method of authentication to load the plug-in's URL securely in the init stage.

HTTP Basic

The HTTP Basic method uses the standard method, which is a part of the HTTP 1.0 standard (RFC 1945) called Basic Access Authentication. It works over HTTPS as well. Check whether your browser supports this, before you decide to use this method. This table describes the three conditions you must fulfill to implement the HTTP Basic method.

Condition Description
Oracle Field Service Configuration On the Forms & Plugins page, select "HTTP Basic" authentication type. Fill up the Login and Password fields. These credentials are encrypted and saved to the Oracle Field Service database.
Server Side Configure the web server on which the plug-in sources are hosted to return the HTTP 401 Unauthorized status, if you are requesting the configured plug-in URL without the credentials. See the NGINX and Apache documents for details.

The server must return the plug-in content if its URL is requested with the HTTP header. Authorization: Basic bXlsb2dpbjpteXBhc3M= Where bXlsb2dpbjpteXBhc3M= is a valid Base64 - encoded pair of login:password. The credentials configured for the plug-in in the Add plugin and Modify plugin pages must be accepted as valid.

Client Side When the user logs in to Oracle Field Service Mobility Cloud Service, Oracle Field Service reads the credentials from the database and loads the plug-in URL into the hidden iframe as follows: <iframe src="https:// mylogin:mypass@example.com/myPlugin.php"/> This way, the browser loads the plug-in sources over HTTPS using HTTP Basic Authentication:
GET /myPlugin.php HTTP/1.1
Host: example.com
Authorization: Basic bXlsb2dpbjpteXBhc3M=

HMAC Authentication

HMAC (Hash based message authentication code) lets you sign HTTP requests and their GET parameters. The HMAC signature ensures that the URL is generated by an authorized source. The MAC signature (digest) is added as an additional GET parameter at the end of a query string: <!CDATA[[http://www.example.com/path?user=test&section=D%26G&activity=33&hmac=D2BJn9P1EcLhaFrNhbAzCQTVQXCCwCBQsrg8V6h4YoU%3D]]>

HMAC Function Algorithm

The algorithm is defined in RFC 2104 , and can be very roughly described as: hmac = BASE64(HMAC-SHA-256(data, SHA256(SecretKey))). SHA - 256 accepts SecretKey as a string and returns the hash string. The secret key is configured per plug-in in the Add plugin and Modify plugin pages in Oracle Field Service Core Application, hashed by SHA256, encrypted and stored in the database. HMAC-SHA-256 accepts data and key as strings and returns a binary array of HMAC signature. BASE64 accepts the binary array and returns BASE64 encoded string. Data required for generating HMAC is query resource location with query parameters sorted lexicographically:
  • Remove the protocol identifier from the URL together with colon and slashes ( http:// or https:// ).

  • Remove the resource name and port from the URL.

  • Append query location to the output string.

  • If there are query parameters append the character ? to the output string.

  • Decode every name and value for URL parameters.

  • Sort the list of parameters alphabetically by name.

  • For each name/value pair:

    • Append the encoded name to the output string.

    • Append the ‘=’ character to the output string.

    • Append the encoded value to the output string.

  • If there are more key/value pairs remaining, append an & character to the output string.

Example: Request URL: http://www.example.com/path?user=test&section=D%26G&activity=33
SecretKey : 'mysecret'
  1. http://www.example.com/path?user=test&section=D%26G&activity=33 => www.example.com/path?user=test&section=D%26G&activity=33

  2. www.example.com/path?user=test&section=D%26G&activity=33 => /path?user=test&section=D%26G&activity=33

  3. data = '/path'

  4. data = '/path?'

  5. ['user'='test','section'='D&G','activity'=33]

  6. ['activity'=33,'section'='D&G','user'='test']

  7. ['activity'=33,'section'='D&G', 'user'='test'] => data

  8. data = '/path? activity'

  9. data = '/path? activity='

  10. data = '/path? activity=33'

  11. data = '/path? activity=33&'

  12. data = '/path? activity=33&section=D %26G&user=test'

hmac = BASE64(HMAC-SHA-256('/path?activity=33&section=D%26G&user=test',SHA256('mysecret'))) = BASE64(HMAC - SHA - 256( '/path? activity=33&section=D %26G&user = test' ,'652c7dc687d98c9889304ed2e408c74b611e86a40caa 51c4b43f1dd5913c5cd0')) = BASE64([0f,60,49,9f,d3,f5,11,c2,e1,68,5a,cd,85,b0,33,09,04,d5,41,70,82,c0,20,5 0,b2,b8,3c,57,a8,78,62, 85]) = 'D2BJn9P1EcLhaFrNhbAzCQTVQXCCwCBQsrg8V6h4YoU='

The full signed URL is 'http://www.example.com/path?user=test&section=D%26G&activity=33&hmac=D2BJn9P1EcLhaFrNhbAzC QTVQXCCwCBQsrg8V6h4YoU%3D'

Sensitive Data

You can set key-value pairs of sensitive data that is securely stored by Oracle Field Service on both, client and server sides. Examples of sensitive data include passwords and endpoints for Oracle Field Service Core API or external APIs.

Sensitive data is passed to the plug-in through the plug-in API in decrypted form, so the plug-in can access APIs or third-party services without having to store and secure the credentials. The plug-in stores the sensitive data in a JavaScript variable every time it receives a message from Oracle Field Service. Changes to this data are sent to Oracle Field Service Mobility Cloud Service during the next synchronization. This data is sent to the plug-in when the next message is sent. The plug-in also receives the up-to-date data with every message.

Configure Sensitive Data

You add sensitive information in the Secure parameters section on the Configuration > Forms & Plugins > Add/Modify plugin page. You can add up to 20 key-value pairs. When the plug-in is modified, JSON is read from the database, decrypted, parsed, and displayed as key-value text box pairs, maintaining original order. Key and values are validated against length limitations in this way:
  • Key-value pairs are translated to JSON.

  • Length of the resulting JSON string (in bytes) is displayed on the page.

  • If the length exceeds 5 KB, a warning message is shown.

Additionally, to prevent request forging, the resulting string is validated on the server to be:
  • Valid JSON string

  • Has correct format

  • Doesn't exceed length limit

If these requirements aren't met, a warning message is shown. Each message sent by Oracle Field Service Core Application to a plug-in, where the method is one of the supported methods, contains the field securedData. Format of the messages for other methods, for example, 'error' does not change. The message contains securedData, if at least one key-value pair is configured on the Configuration > Forms & Plugins > Add/Modify plugin page.

Supported Methods

The securedData parameter is available for the messages of init, open, and wakeup methods.

Format of securedData

securedData is an object, where:
  • Each key is a String, which equals to the contents of "key" text input on the Add/Modify plugin page.

  • Each value is a String, which equals to the contents of "value" text input for the corresponding key on the Add/Modify plugin page.

  • Order of entries is not guaranteed to be identical to the order of key-value pairs on the Add/Modify plugin page.

Example of open method data for Supervisor Plug-in

If your configuration is as given in the screenshot:
This screenshot shows the Secure parameters section on the Add/Modify plugin page.
Here's the message the plug-in receives when opened:
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "resource": {
        "external_id": "33001",
        "manager": "admin"
    },
    "activityList": {
        "4224031": {
            "aid": "4224031"
        }
    },
    "inventoryList": {
        "21064417": {
            "invid": "21064417"
        }
    },
    "securedData": {
        "ofsInstance": "sunrise.test",
        "ofsRestEndpoint": "https://<instance_name>.etadirect.com/rest/",
        "ofsRestClientId": "sample_app",
        "ofsRestClientSecret": "d1e0f03636747b968cd66ead50bd53984e1f1393a3e1503c4e4be9421be00aa5"
    }
}

Export and Import Plug-Ins

When you have plug-ins that work in a similar way, you can export the properties and configuration from one plug-in and import them into another.

  1. Click Configuration > Forms & Plugins.

  2. To export all the plug-ins, click Export Plugins in the header.

  3. To export a single plug-in, locate it and click Export in the action menu.

  4. Save the XML file.

    The selected plug-in is exported with its configuration. Plug-ins with secure parameters are exported with the keys, but without their values.
  5. To import a plug-in configuration, click Import Plugins in the header.

  6. Select the XML file that contains one or more plug-ins.

  7. Click Validation.

    The plug-in is validated and errors, if any, are displayed. Fix the errors and import the file again.
  8. Click OK.

    The plug-in is imported.

Add the Plug-In to a Screen

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.

Plug-In Buttons and Icons

Let's say you use a plug-in that contains several pages and you want to configure links that open different pages of the plug-in. Or, you want to configure different icons for different tiles of the plug-in on the Landing page and change the icon of the tile according to the data in the plug-in.

You can configure the plug-in for all these scenarios, using the Parameters option:
  • Configure parameters for a button associated with a plug-in: You can specify custom parameters for each button of a plug-in. For example, when you click the button, you can open a specific page in the plug-in. You can implement this on multiple pages, by uploading a single plug-in archive.

  • Update icons for a button on the Landing page: You can update the appearance of each button on the Landing Page separately. You can change the icon when you open Oracle Field Service Core Application ('initEnd'), after closing ('close') a plug-in, or when a plug-in receives new data in the background mode ('sleep'). You can also associate each plug-in's page or function with its own icon and text. You can update each icon as needed, no matter with which button you open the plug-in.

How it Works

The data sent to the plug-in during initialization includes the list of all buttons configured for each plug-in with the key-value pairs of configured parameters. When a user opens the plug-in, the ID of the button is passed to the plug-in with the parameters configured for this button. When a user closes the plug-in, you can redirect the user to another plug-in, as if the plug-in has been opened through a button, and parameters that are configured for this button are passed to the plug-in.

Modify the Icons and Text of a Plug-In Tile

You can implement a flexible flow for the buttons of a plug-in on the Landing Page. You can change the icons on the buttons individually, or all at once. The icon can be changed when the Oracle Field Service Core Application is opened ('initEnd'), after plug-in is closed ('close'), or when a plug-in gets new data in the background mode (‘sleep’). See the Example of Changing Buttons in a Plug-in topic to understand how it works.

List of all buttons that are configured for a plug-in is sent to the plug-in in the 'buttons' field of the 'init' message. This field is a list of objects that contain the 'buttonId' and 'params' fields. buttonId is the 'context layout item id' of the button. 'params' is an object that represents the parameters that are configured for the corresponding context layout item.

The 'open' message contains the buttonId and openParams fields. buttonId is the 'context layout item id' of the button that the user clicks to open the plug-in. openParams contains the parameters that are configured for this button.

If a plug-in is opened by sending the backScreen: "plugin_by_label" from another plug-in, the buttonId and openParams fields are sent in accordance with the backPluginButtonId param of the 'close' message. If the backPluginOpenParams field of the 'close' message contains the key, which is already configured for the button, the openParams field contains the value that's sent in backPluginOpenParams.

If backPluginButtonId was not set, the 'open' message doesn't contain the buttonId and openParams fields. This table shows the data in the 'init', ‘open’ and ‘close' messages that is used for changing appearances:

Message Type Field Description
init buttons List of objects that contain the 'buttonId' and 'params' fields.
  • buttonId: Context layout item id of the button.

  • params: Object that represents the parameters, configured for the corresponding context layout item.

open buttonId Context layout item id of the button that the user clicks to open the plug-in.
openParams The parameters that are configured for this button.
close buttonId Context layout item id of the button that the user clicks to open the plug-in.
openParams The parameters that are configured for this button.
backPluginButtonId
init Message
{
    "apiVersion": 1,
    "method": "init",
    "attributeDescription": {
        "aid": {
            "fieldType": "field",
            "entity": "ENTITY_ACTIVITY",
            "gui": "text",
            "label": "aid",
            "title": "Activity ID",
            "type": "string",
            "access": "READ_WRITE"
        }
    },
    "buttons": [
        {
            "buttonId": "17155",
            "params": {
                "defaultScreen": "order-part",
                "someOptions": "{showCart: true}"
            }
        },
        {
            "buttonId": "17156",
            "params": {
                "defaultScreen": "search-parts"
            }
        }
    ]
}
open Message
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "resource": {
        "pid": 8100059
    },
    "activityList": {
        "4225376": {
            "aid": "4225376"
        }
    },
    "inventoryList": {},
    "buttonId": "17155",
    "openParams": {
        "defaultScreen": "order-part",
        "someOptions": "{showCart: true}"
    }
}
close Message: Navigate to Another Plug-in
{
    "apiVersion": 1,
    "method": "close",
    "backScreen": "plugin_by_label",
    "wakeupNeeded": false,
    "backPluginLabel": "sample_plugin",
    "backPluginButtonId": "17155",
    "backPluginOpenParams": {
        "someOptions": "{ anotherOption: 123 }",
        "thirdParam": null
    }
}
open Message: Navigated from Another Plug-In
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "resource": {
        "pid": 3000001
    },
    "activityList": {},
    "inventoryList": {},
    "buttonId": "17155",
    "openParams": {
        "defaultScreen": "order-part",
        "someOptions": "{ anotherOption: 123 }",
        "thirdParam": null
    }
}
close Message: Update Icons
{
    "apiVersion": 1,
    "method": "close",
    "backScreen": "default",
    "wakeupNeeded": false,
    "buttonsIconData": {
        "17156": {
            "color": "highlight",
            "text": "123",
            "image": {}
        },
        "17155": {
            "color": "default",
            "text": null,
            "image": {}
        }
    }
}

Example of Changing Buttons in a Plug-In

Consider the example of a catalog and a cart. The Order List Button changes its color when the supervisor approves the order.

  1. There's a plug-in, which implements three pages: "Catalog", "Cart" and "Order List". Each button has a corresponding icon:
    This screenshot shows the Cart, Catalog, and Order List buttons in a plug-in.
  2. User clicks "Catalog" and the plug-in shows the list of items available for order.

  3. User selects the items to order and closes the plug-in page.

  4. The plug-in updates the "Cart", so that it shows the count of the items in the cart:
    This screenshot shows the count of items on the Cart button in a plug-in.
  5. User clicks "Cart" and the plug-in shows the list of ordered items.

  6. User confirms the order and closes the plug-in page.

  7. The plug-in clears the counter on the "Cart" button and updates the "Order List" button so it shows the number of orders for approval:
    This screenshot shows the Cart button counter cleared and the Order List button updated in a plug-in.
  8. The plug-in prompts Oracle Field Service to run it in the background every five minutes to get the updated information from the server.

  9. The supervisor of the user approves the order.

  10. The plug-in runs in the background and receives the updated status of the order from the server. It clears the counter on the "Order List" button and highlights it:
    This screenshot shows the counter cleared on the Order List button and the button highlighted.

    User sees that the order is processed and approved without the need to reopen the plug-in.