2Application APIs

Application APIs

Oracle Field Service Cloud APIs supports integration of Oracle Field Service Cloud with the corporate systems of a client company, enabling a wide variety of actions, from getting data into Oracle Field Service Cloud to integration into a client's existing mobile application.

    Users

    User is a person, group of people or software accessing Oracle Field Service Cloud with a single login to the system. Each user in Oracle Field Service Cloud can manage only resources assigned to the user. You can assign user types to users to define a set of permissions for determining what the user can see and manage in the system.

    Each time any SOAP-API transaction is run in Oracle Field Service Cloud, the user authentication is run. Basically, authentication is a process of verifying that the user is in fact who they claim to be.

    An Authentication check is described among common API structures of all the SOAP and REST APIs. More detailed description of the user processing is provided in the correspondent SDK of each specific API that processes the users.

      Resources

      When the system is implemented, it is populated with company-specific resources.

      Resource is one of the basic entities of Oracle Field Service Cloud which deals directly with activities.

      There are several resource types in Oracle Field Service Cloud. For more information, see the Resource types section in the Administering Oracle Field Service Cloud Guide.

        Activities

        Activities can be added to Oracle Field Service Cloud and then manually or automatically allocated among field resources. Activity is a time-consuming action. By default, there are three types of activities, namely, internal, customer, and team work. However, activity types can be configured. New activity types can be created, while the default types can be removed, if needed. More detailed description of the activity processing is provided in the correspondent SDK of each specific API that processes the activities.

          Properties

          Property is a variable associated with some Oracle Field Service Cloud entity (resource, user, activity, inventory, etc).

          This is much like a field of an object in most programming languages. Property has a name, visibility, data representation, relations to entity and modification parameters.

          Therefore, if there is a property of an entity in Oracle Field Service Cloud, all such entities have this property, and all relevant API functions can read this property, write to it, and make conditional decisions based on the property value (as long as correspondent permissions are granted to a user). Correspondingly, all screens and functions, having access to the entity, can as well operate its properties (according to visibility restrictions).

          Properties for Oracle Field Service Cloud entities can also be updated. A more detailed description of the property processing is provided in SDK of each specific API that processes the properties.

            Inventories

            Inventory is any equipment which is installed or deinstalled during an activity performance. Inventory could be virtually anything that is used in a job from consumable material to a set of instruments, or devices. Inventory can belong to any resource or customer. Basically, inventory is a property of an activity, but inventory in turn, can have own properties (e.g. type of inventory). A more detailed description of the inventory processing is provided in SDK of each specific API that processes the inventories.

              Required Inventories

              Required inventory is the inventory necessary to complete a certain activity. If any required inventory is defined for an activity, such required inventory is regarded as one of the criteria of activity assignment to resources. The required inventory is checked against the resource's inventory to see whether the resource's inventory is sufficient to complete the activity. If the resource has no required inventory in their pool, the activity will not be assigned to such resource. A more detailed description of the required inventory processing is provided in SDK of each specific API that processes the required inventory.

                Work Skills

                One of the properties defined for a resource is a set of work skills that the resource obtains and qualification level for each skill. A work skill is a task that a resource is qualified to perform. Work skills are assigned to technicians based on their training and knowledge. The names of the work skills may vary in different companies and industries.

                Along with that, a set of rules is defined that enables automatic calculation of the work skills of each activity, their required and preferable levels. An activity should be assigned to a resource that obtains all of the work skills necessary to perform an activity with qualification level not less than the required level for the activity. A more detailed description of the work skills processing is provided in the correspondent SDK of each specific API that processes the work skills.

                  Work Zones

                  One of the properties defined for a resource is a set of work zones. A work zone is a defined geographical area where a resource can perform their service. A temporary work zone is a work zone that is not a resource's typical work zone, but that is assigned to the resource for a period of time. Temporary work zones will override a resource's regular work zones.

                  Along with that, a set of rules is defined that enables automatic calculation of the work zone of each activity. An activity should be assigned to a resource that can perform work in the work zone of the activity. A more detailed description of the work zones processing is provided in the correspondent SDK of each specific API that processes the work zones.

                    Message Scenarios

                    Oracle Field Service Cloud provides ability to create and trigger message scenarios. A Message Scenario is a collection of one or more Message Steps, defining message content, recipient, delivery protocol, and delivery business rules.

                    A Message Scenario defines a set of rules that tells how to do a specific notification. These rules are triggered by an internal event or certain conditions (Cancel, Complete, Change, and so forth).

                    Message Scenarios enable the following actions to be executed (by default):

                    • Sending an e-mail

                    • Making an outbound voice call

                    • Changing a property of a technician, an activity or a user

                    • Sending a message to an external system

                    More actions can be configured according to a company's requirements. A more detailed description of the message processing is provided in the correspondent SDK of each specific API that processes messages.

                      Service Request

                      Service request is a message generated as the result of the 'send Service Request' operation and assigned to a specific entity in Oracle Field Service Cloud. A more detailed description of the service requests processing is provided in the correspondent SDK of each specific API that processes the service requests.

                        Route

                        Route is a list of activities assigned to a resource for a specific date, or a list of non-scheduled activities assigned to a resource. A route may contain zero or more activities.

                        One workday of one technician defines a route. Any references to the 'date' of the route mean the date of the workday start (e.g. if the resource works overnight).

                        Initially the route is formed in accordance with the resource calendar for every active resource with the working time scheduled for the date. The route of a resource can be filled with activities. When a user to which such resource is assigned has logged into the system the user can manage the route. A more detailed description of the route processing is provided in the correspondent SDK of each specific API that processes the routes.

                          Oracle Field Service Cloud API List

                          The following APIs are available for Oracle Field Service Cloud. The APIs below are listed in the alphabetical order:

                            API Introduction

                            Oracle Field Service Cloud (OFSC) logs changes made to activities, inventory, routes, etc. The history records the performed operation, the time of such operation, the user which performed the operation and the actual changes which were made. The History API serves as an advanced means of retrieving such actions and their details for further use by external applications.

                            Events are logged in history and become available for retrieval as soon as they occur. This allows real-time data collection and processing which creates a dynamic picture of OFSC performance.

                              Capacity Management API

                              The function of the Capacity Management API is to:

                              • Extract all data available in the Quota View of Oracle Field Service Cloud.

                              • Set or update the quota parameters.

                              • Retrieve, set, or update the time when the quota is to be closed automatically.

                              • Determine quota available for an activity to be booked and provide this information to the system where this booking is actually performed.

                                Positioning API

                                Positioning API supports integration of the Oracle Field Service Cloud system with external GPS-based systems, providing position tracking of GPS-enabled devices.

                                Positioning API allows to:
                                • Enable the Oracle Field Service Cloud system to obtain information about last known position of objects specified by identifiers and history of their movements.
                                • Enable the external system to update information about the last known position of objects specified by identifier.

                                  Detailed information on the methods used by Positioning API can be found in the corresponding GPS SDK.

                                  History API

                                  History API serves as an advanced means of retrieving history logs and their details for further use by external applications.

                                  History API uses one method to retrieve history records of changes to the following entities of Oracle Field Service Cloud:
                                  • Route

                                  • Activity

                                  • Activity link

                                  • Resource preference

                                  • Required inventory

                                  • Inventory

                                  • Service request

                                    Detailed information on the methods used by History API can be found in the corresponding History SDK.

                                    Inbound API

                                    The Inbound Interface is used to import data from a client external system to Oracle Field Service Cloud.

                                    Inbound Interface is implemented as SOAP function for the following purposes:

                                    • Set activities for a specific day for all resources or resource groups in Oracle Field Service Cloud.
                                    • Add new activities to Oracle Field Service Cloud.

                                    • Update, reassign, reschedule, and cancel activities in Oracle Field Service Cloud.

                                    • Change an activity status in Oracle Field Service Cloud.

                                    • Delete activities from Oracle Field Service Cloud.

                                    • Set inventory for resources and activities in Oracle Field Service Cloud.

                                    • Update or delete specific inventory in Oracle Field Service Cloud.

                                      The upload can differ in the object uploaded: activities or resource inventories; and in the scale of upload: full or incremental. Detailed information on the methods used by Inbound API can be found in the corresponding Inbound Interface SDK.

                                      Outbound API

                                      Outbound API is used for interaction between the Oracle Field Service Cloud message engine and external Client Application. Client Application is a software that is developed to integrate Oracle Field Service Cloud with external system(s). Client Application SOAP Service implements the following operations called by Oracle Field Service Cloud:

                                      • Send messages to Client Application.

                                      • Check if the message is still being processed.

                                      • Remove message from the agent internal queue, if the need in such message no longer present.

                                      • Optionally changing properties of an activity and/or activity status.Update or delete specific inventory in Oracle Field Service Cloud.

                                        Detailed information on the methods used by Outbound API can be found in the corresponding Outbound Interface API guide.

                                        Detailed information on configuring the outbound messages can be found in the Notification Configuration Guide. The recommended use for the Outbound Interface is for time-based notifications (for example, notifications to customers) typically using the Reminder and Change notification triggers. For all other system events (for example, Route changes, Activity status changes, Inventory changes, Service Request changes, and so on), it is recommended to use the Core API/Events REST API for integration.

                                        Parts Catalog API

                                        Parts Catalog API provides a set of functions used to manage the Oracle Field Service Cloud Parts Catalog. They are as follows:

                                        • Create a new catalog.

                                        • Start and upload transaction for an existing catalog.

                                        • Upload data to an existing catalog.

                                        • Close an upload transaction for an existing catalog.

                                        • Abort the current transaction and delete all data uploaded during such transaction.

                                        • Search for existing catalogs.

                                        • Upload item weights to an existing catalog.

                                        • Delete item weights from an existing catalog.

                                        • Update inventory types or the item types in the catalog.

                                        • Delete all catalog data.

                                        • Get the list of transactions for an existing catalog.

                                          Detailed information on the methods used by Parts Catalog API can be found in the corresponding Parts Catalog API guide.

                                          Location API

                                          The Location API provides a simple and structured way to communicate with Oracle Field Service Cloud service. This API allows to remotely update Oracle Field Service Cloud Location-Based Services to change their storages with resource data from the third-party providers that is needed to search for locations. This API provides a complete set of methods to monitor the location / traces of resources the client uses for Oracle Field Service Cloud, namely:

                                          • Update the service with the current location of resource.
                                          • Retrieve the last location which was set for the resource.

                                          • Retrieve the company-specific properties which were set with the attributes parameter for the last location of the resource.

                                          • Return the history of positioning for the given resource during the specific period of time.

                                          • Filter the history by applying the algorithm reducing the number of points in a curve, that is approximated by a series of points.

                                          • Retrieve the information about the location of resources within the area defined by the longitude, latitude, and radius parameters.

                                            Detailed information on the methods used by Location API can be found in the corresponding Smart Location API guide.

                                            Metadata API

                                            The Oracle Field Service Cloud Metadata API provides REST-based services that can be used to manage the configuration elements (for example, work zones) of Oracle Field Service Cloud. The Metadata API provides a new, modern way to manage Oracle Field Service Cloud configurations.

                                              Activity Management API

                                              Oracle Field Service Cloud Activity Management Application Programming interface can be used throughout the activity lifecycle and enables integration of the Oracle Field Service Cloud activity management functionality in any software regardless of the platform or technology used, providing efficient tool for dynamic management and update of activity-related properties. Basic entities processed with the Activity Management API are activities and activity properties.

                                              The Activity Management API provides methods to manage routes and activities, creating and processing them, and changing their details, namely:

                                              • Retrieve properties of the activities in the specified resource's route for a specified day, as well as start, restart, or end the route

                                              • Create activities with the specified properties assigned to the specified resource. Manage the resource's route by changing activity statuses and their start and end times

                                              • Alter activity details applicable to a given activity regardless of its status

                                              • Retrieve specified activity details and work skills

                                              • Define, retrieve, and delete required, preferred, and forbidden resources to perform the specific activity

                                              • Define, retrieve, and remove specified dependencies between two specified activities

                                              • Define a file property, retrieve details of the specified property, and delete the file property with the specified label

                                              • Define, retrieve, and delete required inventory for (from) the activity.

                                              Detailed information on the methods used by Activity Management API can be found in the corresponding Activity Management SDK.