Business Flows
The integration scope supports the following business processes:
Process Work Tasks (Oracle Integration Cloud Scheduled Job)
This integration flow is used to synchronize the work request or work order created in ESRI ArcGIS Field Maps connected to ArcGIS Online or ArcGIS Enterprise to Oracle Field Service. Work request can be created with or without an asset and work order is always created with asset in ESRI ArcGIS Field Maps.
The integration synchronizes the same to Oracle Field Service and also updates the ESRI ArcGIS Field Maps records with Oracle Field Service work order/work request ID.
The following diagram shows a graphical representation of the Process Work Tasks integration process:
Business Processing
This scheduled integration process includes the following activities:
1. The Oracle Utilities Work Tasks Process flow is a scheduled integration. It operates asynchronously, allowing both manual execution and scheduling to retrieve the work order/work requests from ESRI ArcGIS Field Maps and create it in Oracle Field Service.
2. The process queries the ESRI ArcGIS Field Maps Tasks feature layer for unprocessed work order or work requests.
3. The process checks if the records contain GIS ID or not.
4. If the ESRI ArcGIS Field Maps record contains the GIS ID, then assetQuery and assetDetails in Oracle Utilities Work and Asset Cloud Service are invoked to get all the asset details.
5. The process checks if the records are work order or work request, transforms the message into the Oracle Field Service format, and invokes the bulk update API to create a work order and service request API to create a work request in Oracle Field Service.
6. If the work order and work request creation is successful in Oracle Field Service, the integration process does the following:
a. Transforms the Oracle Field Service response and adds the activity ID to the successful work order records.
b. Transforms the Oracle Field Service response and adds the request ID to the successful work request records.
7. If the work order/work request creation is unsuccessful in Oracle Field Service, the integration process does the following:
a. Transforms the fault response and adds the fault message to the unsuccessful records list.
8. The process flow updates the successful records in the ESRI ArcGIS Field Maps Task layer to make sure the successful records will not be retrieved in the next run.
9. The process flow sends an email notification with an attachment containing the failure records information and error details.
10. Any unrecoverable errors thrown are handled by the global fault handler.
11. An optional email notification with error details is sent to the users configured in the OUTL-BRT-ArcGIS_OFS_Email_ID lookup.
12. Email notification is optional. Configure the property email.flag in the OUTL-BRT-ArcGIS_OFS_ConfigProps lookup to ‘true’ to receive email notifications when errors are encountered.
Technical Details
The following table describes the integration processes and the respective ESRI ArcGIS Field Maps and Oracle Field Service artifacts used in this integration process.
Artifacts | Value |
|---|---|
OFSC BO/Operation | Activity/Bulk Update Activity |
OFSC API | • /rest/ofscCore/v1/activities/custom-actions/bulkUpdate • /rest/ofscCore/v1/serviceRequests |
WACS BO | • W1-AssetQuery • W1-GetAstDtl |
Integration Process Name | OU ArcGIS OFS Work Tasks Process |
Integration Project Name | OU ESRIArcGIS OFS |
Source Connection (Oracle Utilities Adapter) | OU SOAP WACS for ArcGIS-OFS |
Target Connection (Rest Adapter) | • OU REST ArcGIS for ArcGIS-OFS • OU REST OFS API for ArcGIS-OFS • OU REST OFS for ArcGIS-OFS |
OIC Lookups | • OUTL-BRT-ArcGIS_OFS_ConfigProps • OUTL-BRT-ArcGIS_OFS_Email_ID • OUTL-BRT-ArcGIS_OFS_ActivityType |
Lookups Referenced
The following table describes customized properties referenced in the integration. For more information about the lookup properties, refer to Configuring Lookups, Error Handling, and Email Notifications.
DVM | Property |
|---|---|
OUTL-BRT-ArcGIS_OFS_ConfigProps | • notifcation.email.error.flag • asset.inventory.type • ofs.default.bucket |
OUTL-BRT-ArcGIS_OFS_Email_ID | • from • to |
OUTL-BRT-ArcGIS_OFS_ActivityType |
Integration Properties
Property Name | Comments |
|---|---|
addLocInfo | Property used to append the geo location X and Y values from ARCGIS record to WO/WR description in OFS if it is set to 'Y'. Valid values are 'N' or 'Y'. |
queryParameter | Property used to query the unprocessed ArcGIS records. The value will be used as query parameter as part of the query feature layer request. (EXTERNAL_REC_INFO='N') |
workTasksLayerRelativeURI | Relative URI of the Work task feature layer after /rest/service in the feature layer rest service URL. The URI begins with “/”. Example: /WorkTasks/FeatureServer/0 |
Create Admin Files (Oracle Integration Cloud Scheduled Job)
This integration process synchronizes the fields and values found in the work order and work request form the drop down in ESRI ArcGIS Field Maps with values from Oracle Utilities Work and Asset Cloud Service. Operating as a one-way, asynchronous process, it updates the latest values and relationships from Oracle Utilities Work and Asset Cloud Service, generating CSV files that are then uploaded to a designated Object Storage Bucket. In ESRI ArcGIS Field Maps, these fields and values are referred to as Domain Values (DV) and their related field values as Contingent Values (CV). The integration process produces specific files which can then be manually uploaded to the Tasks feature layer through ArcGIS Pro.
For more information on this update process, refer to the ESRI ArcGIS Field Maps Integration to Oracle Field Service Mobile Setup Guide included in this release. The integration documentation is available on Oracle Help Center at: https://docs.oracle.com/en/industries/energy-water/integrations-index.html
The domain value files are:
• WorkType
• WorkPriority (A schema.ini file will also be generated)
• ActivityTypes
• GroupTypes
• WorkClass
• WorkCategory
The contingent value files are:
• ContingentVal
• FieldGroup
The following diagram shows a graphical representation of the Create Admin Files integration process:
Business Processing
The integration process includes the following activities:
1. Initialization Phase
• This is a scheduled integration. It operates asynchronously, allowing both manual execution and scheduling.
• It uses the following integration properties that take effect during runtime:
• groupType: Defaults to “WACS” identifies the source of the domain value and contingent value files.
• arcgisOSNamespace: Specifies the cloud object storage namespace for file uploads.
• arcgisOSBucket: Determines the cloud object storage bucket name for file storage.
• includeOIDWorkPriority: Defaulted to “Y”, this setting allows ArcGIS Pro to import priority values as numbers rather than strings, ensuring correct data interpretation.
• sourceExternalSystem: By default, set to “OFSC”, this identifies the target system for field values retrieved from Oracle Utilities Work and Asset Cloud Service.
• Parameters set during each run dictate the generation of specific files with the descriptions in the language specfied:
• Language: Defaults to “ENG” to extract specific translation values for domain values and contingent values.
Note : The files generated are prefixed with language value of this parameter.
• Work_Category-Work_Class: Defaults to “Y” to generate WorkClass.csv and WorkCategory.csv files; “N” skips generation. This action also produces ContingentVal.csv and FieldGroup.csv.
• ActivityType: Defaults to “Y” to generate ActivityTypes.csv file; “N” skips generation.
• Group_Type: Defaults to “Y” to generate the GroupType.csv file; “N” skips generation.
• Work_Type: Defaults to “Y” to generate WorkType.csv file, “N” skips file generation.
• Work_Priority: Defaults to “Y” to generate WorkPriority.csv file; “N” skips CSV file generation. This action may also create a schema.ini file.
2. Retrieve Oracle Utilities Work and Asset Cloud Service Admin Data.
• Utilizing the Oracle Utilities Adapter, field values are fetched from the Oracle Utilities Work and Asset Cloud Service SOAP catalog through the External Mobile Control Data service (/W1-ExtMbCnDa).
• Language codes (default ENG) affect translation values and file naming, excluding schema.ini.
3. Processing Files
• CSV files are created according to the parameters defined in the initialization phase and are temporarily stored in Oracle Integration Cloud. Subsequently, these files are uploaded to the designated object storage bucket, and a language suffix is added to each filename.
• In the processing of particular files, additional actions may be executed based on the type of file and specific integration configurations:
• When the WorkPriority file is in the process of being generated and the integration property includeOIDWorkPriority is enabled (“Y”), a schema.ini file will also be produced. This facilitates ArcGIS Pro to accurately import Priority values as numerical rather than string types, ensuring the data is interpreted correctly.
• When generating Work_Category-Work_Class files in addition to the standard domain value files, contingent value files, namely FieldGroup.csv and ContingentVal.csv, will be generated. These files capture the relationship between the two entities. If there are instances where WorkCategory values are not related to WorkClass as returned by WACS, CV_VALUE2 is set to ‘1’. This configuration indicates that ArcGIS will permit the association of any WorkClass value to that particular WorkCategory value, without issuing warnings.
4. Business Notification Email
• A completion email is triggered based on the notification.email.process.complete.flag setting. If this flag is set to indicate an email should be sent, an email will be dispatched, enumerating the files generated and uploaded to the object storage bucket, thus giving a brief summary of the integration’s results.
5. Error Handling
• When there is service unavailability or data retrieval failures from External Mobile Control Data, External Mobile Activity Types, or Object Storage, the following occurs:
• The integration process stops immediately if the failure originates in the External Mobile Control Data service at the onset. A technical error email is sent (if notification.email.error.flag is ‘true’), an exception is thrown, and the Oracle Integration Cloud instance is marked as Failed.
• For failures during data retrieval from External Mobile Activity Types or if Object Storage is not working:
• The files already in Object Storage remain.
• The flow records the error details, but continues to subsequent files.
• At the end, a summary notification email and, if applicable, a Technical Error Detail email is/are sent.
• The Oracle Integration Cloud instance is marked as ‘Failed’.
• For other errors, the integration process gathers error details and proceeds to the next file. Upon completion, it sends out notification emails, depending on the configuration set in the lookups for Business Notification email and Technical Error email. Finally, the status of the Oracle Integration Cloud instance is marked as ‘Failed’.
Technical Details
The following table describes the integration processes and the respective ESRI ArcGIS Field Maps and Oracle Field Service artifacts used in this integration process.
Artifacts | Value |
|---|---|
Integration Process Name | OU WACS ArcGIS Admin Files Create |
Integration Process Identifier | OUTL-BA-ARCGIS_OFS_ADM_CRT |
Integration Project Name | OU ESRIArcGIS OFS |
Source Connection (Oracle Utilities Adapter) | OU SOAP WACS for ArcGIS-OFS |
Target Connection (Rest Adapter) | OU REST ArcGIS OS for ArcGIS-OFS |
OIC Lookups | • OUTL-BRT-ArcGIS_OFS_ConfigProps • OUTL-BRT-ArcGIS_OFS_Email_ID |
Lookups Referenced
The following table describes customized properties referenced in the integration. For more information about the lookup properties, refer to Configuring Lookups, Error Handling, and Email Notifications.
DVM | Property |
|---|---|
OUTL-BRT-ArcGIS_OFS_ConfigProps | • notifcation.email.error.flag • notification.email.process.complete.flag |
OUTL-BRT-ArcGIS_OFS_Email_ID | • from • to • to.process.notification |
Delete Activities (Oracle Integration Cloud Scheduled Job)
This scheduled process fetches activities from the ArcGIS Activities feature class with statuses (Suspended, Cancelled, and Completed) that are older than a specified number of days. Each status has a separate parameter for data retrieval. The process invokes ArcGIS deleteFeatures API to delete the corresponding Activities and Assets by status separately. This process makes sure that Field Crews access only relevant, recent activities information in Field Maps, such as ongoing pending activities.
The following diagram shows a graphical representation of the Delete Activities integration process:
Business Processing
The integration process includes the following activities:
1. Initialization phase
• This is a scheduled integration. It operates asynchronously, allowing both manual execution and scheduling.
• It uses the following integration properties that take effect during runtime:
• activitiesLayerRelativeURI: Specifies the relative URI of the Activities feature layer rest service. This is relative URI after /rest/services/ of the Activities feature layer endpoint within ESRI ArcGIS Field Maps.
• Parameters set during run determine the criteria for deleting activities based on their age and status:
• Cancelled_days: Specifies the number of days prior to today on which cancelled activities will be deleted. Acceptable values are zero and positive integers.
Example: ‘0’ is all days prior to today, ‘1’ is all days prior to yesterday.
• Suspended_days: Specifies the number of days prior to today on which suspended activities will be deleted. Acceptable values are zero and positive integers.
Example: ‘0’ is all days prior to today, ‘1’ is all days prior to yesterday.
• Completed_days: Specifies the number of days prior to today on which completed activities will be deleted. Acceptable values are zero and positive integers.
Example: ‘0’ is all days prior to today, ‘1’ is all days prior to yesterday.
2. Delete the related activities and assets in ESRI ArcGIS Field Maps.
• Utilizing the Oracle Rest Adapter invoke the deleteFeatures operation to remove activities based on the parameters specified during the initialization phase.
• When a parent record in Activities feature class is deleted, the child records in ActivityAssets feature are automatically deleted.
• When the Activities feature layer is deployed on ArcGIS Online, the deleteFeatures API returns has the number of records deleted. The integration process will count and record the number of deletions per each status. When Activities feature layer is deployed on ArcGIS Enterprise, the API does not return the number of records deleted.
3. Business notification email
• An email is dispatched upon completion based on the notification.email.deleteactivities.flag setting, which is initially set to ‘false’.
• Activities feature layer on ArcGIS Online: When flag is ‘true’ and the integration process is connected to a Activities feature layer on ArcGIS Online, the email details the number of activities deleted by each status.
• Activities feature layer on ArcGIS Enterprise: When connected to an ArcGIS Enterprise and the flag is ‘true’, the email will merely confirm the successful execution of the integration flow, without detailing the deleted activities.
4. Error handling
• Functional errors: If ArcGIS reports functional errors during the deletion of activities, or if there are invalid parameter values used during the initialization phase, the integration flow will capture these errors.
• At the end of the process, an email is sent regardless of the notification.email.deleteactivities.flag setting in the OUTL-BRT-ArcGIS_OFS_ConfigProps lookup, ensuring that relevant parties are informed of any issues.
• Target recipients are defined in the OUTL-BRT-ArcGIS_OFS_Email_ID lookup under “to.process.notification”.
• The Oracle Integration Cloud instance will finish successfully regardless of the functional errors.
• Technical errors: Any technical error, such as token expiry on the connection, will cause the process to halt immediately.
• An email detailing the error will be sent if the notification.email.error.flag in the OUTL-BRT-ArcGIS_OFS_ConfigProps lookup is set to ‘true’.
• Target audience for the email is specified in the OUTL-BRT-ArcGIS_OFS_Email_ID lookup under “to”.
• An exception will be thrown, and the Oracle Integration Cloud instance will be marked as ‘failed’.
• After fixing the error, the flow can either be manually trigger or wait for the next scheduled iteration.
Technical Details
The following table describes the integration processes and the respective ESRI ArcGIS Field Maps and Oracle Field Service artifacts used in this integration process.
Artifacts | Value |
|---|---|
Integration Process Name | OU OFS ArcGIS Activities Delete |
Integration Process Identifier | OUTL-BA-OFS_ARCGIS_ACT_DEL |
Integration Project Name | OU ESRIArcGIS OFS |
Target Connection (Rest Adapter) | OU REST ArcGIS for ArcGIS-OFS |
OIC Lookups | • OUTL-BRT-ArcGIS_OFS_ConfigProps • OUTL-BRT-ArcGIS_OFS_Email_ID |
Lookups Referenced
The following table describes customized properties referenced in the integration. For more information about the lookup properties, refer to Configuring Lookups, Error Handling, and Email Notifications.
DVM | Property |
|---|---|
OUTL-BRT-ArcGIS_OFS_ConfigProps | • notifcation.email.error.flag • notification.email.deleteactivities.flag |
OUTL-BRT-ArcGIS_OFS_Email_ID | • from • to • to.process.notification |
Activities Sync (Oracle Integration Cloud Scheduled Job)
This scheduled process fetches and synchronizes the activities from Oracle Field Service on specified start and end date and inserts or updates the activities to the ArcGIS Activities feature class. Also, this flow inserts/updates the activities in ArcGIS with status specified in the configuration property.
If startDate and endDate is specified as NA, the current date will be taken as start and end dates as parameters.
This flow also searches the assets of specific activity from the OFS and insert/update the ActivityAssets table in ESRI ArcGIS Field Maps.
The following diagram shows a graphical representation of the Activities Sync integration process:
Business Processing
The integration process includes the following activities:
1. Initialization phase.
• This is a scheduled integration. It operates asynchronously, allowing both manual execution and scheduling.
• It uses the following integration properties that take effect during runtime:
• activitiesLayerRelativeURI: Specifies the relative URI endpoint of the Activities feature layer. This is relative URI after /rest/services/ of the Activities feature layer endpoint within ESRI ArcGIS Field Maps.
• activitiesAssetsLayerRelativeURI : Specifies the relative URI endpoint of the ActivityAssets table. This is relative URI after /rest/services/ of the ActivityAssets feature layer endpoint within ESRI ArcGIS Field Maps.
• assetLayerIds: Configure all the feature layer IDs of the GIS assets in ESRI ArcGIS Field Maps. The flow uses these feature layer IDs to find the correct layer ID of the given asset GIS ID as part of the Find Rest API, which is part of MapServer.
2. Query activities and assets from Oracle Field Service.
• Utilizing the Oracle Rest Adapter invoke the getActivities API from Oracle Field Service to get the activities from Oracle Field Service for specific start and end date.
• Utilizing the Oracle Field Service Adapter invoke the getCustomerInventories API to get the assets related to an activity from Oracle Field Service.
• Utilizing the Oracle Field Service Adapter invoke the get ResourceDetails API to get the resource name and time zone from Oracle Field Service.
3. Query activities and assets from ESRI ArcGIS Field Maps.
• Utilizing the Oracle Rest Adapter invoke the Activities feature layer API to get the activities from ArcGIS for specific start and end date of an activity stored in the ACTIVITY_DATE field.
• Utilizing the Oracle Rest Adapter invoke the ActivityAssets feature layer API to get the assets from ESRI ArcGIS Field Maps on specific start and end date of an activity stored in the ACTIVITY_DATE field.
4. Processing each activity and assets, and preparing the create/update payload for activity and asset records.
• For each Oracle Field Service activity (matching start date and end date), if the Oracle Field Service activity ID matches the activity ID stored in Activities feature class:
a. Prepare the activity update payload.
b. Else, prepare the activity create payload.
• For each Oracle Field Service activity:
a. Get the assets from Oracle Field Service by invoking the getCustomerInventories API from Oracle Field Service.
b. For each retrieved assets from the ActivityAssets table:
a. If the activity ID and asset ID match with the ESRI ArcGIS Field Maps activity asset record, prepare the asset update payload.
b. Else, prepare the asset create payload.
• Finding the asset search value:
You can configure a popup for the Activities feature layer in Webmaps to show the activities and related assets information from the ActivityAssets table. These assets can be linked to a Field Maps search URL using Arcade expression. A SEARCH_VALUE field in the ActivityAssets table stores the search value that can be used to search this asset on the map.
A SEARCH_VALUE field is populated based on the configurations in the OUTL-BRT-ArcGIS_OFS_AssetSearchField OIC lookup table. This lookup has three columns:
• FeatureLayerID: ID of the corresponding Asset in ESRI ArcGIS Field Maps.
• SearchField_1: A configured search field for this layer in ESRI ArcGIS Field Maps Webmap/Field Map.
• SearchField_2: A configured search field for this layer in ESRI ArcGIS Field Maps Webmap/Field Map. This field will be looked at if the SearchField_1 attribute returns empty or null.
Currently, we can configure only two search fields in the ArcGIS_OFS_AssetSearchField OIC lookup. If one search field element value is empty, map the second search field element value.
To assign the search field value:
a. Gets the feature layer ID from the OUTL-BRT-ArcGIS_OFS_AssetSearchField lookup based on the asset type.
b. Get the asset details using gisID by invoking the ArcGIS Query API.
c. Assign the SearchField_1 and SearchField_2 values from the OUTL-BRT-ArcGIS_OFS_AssetSearchField lookup.
d. Extracts the attribute data from the asset response payload.
e. If the SearchField_1 value is not empty, get the attribute value corresponding to SearchField_1 using the ArcGISOFS_GetSearchValFromResponse library and assign it to the asset payload SEARCH_VALUE element.
f. If the SearchField_1 value is empty and SearchField_2 value is not empty, get the attribute value corresponding to SearchField_2 using the ArcGISOFS_GetSearchValFromResponse library and assign it to the asset payload SEARCH_VALUE element.
5. Add/update the related activities and assets in ESRI.
• Utilizing the Oracle Rest Adapter, invoke the applyEdits operation to add or update activities and assets in the Activities feature class and ActivityAssets table.
6. Business Notification Email
• If any invalid activities are identified, an email will be sent to the respective email IDs configured in the ArcGIS_OFS_Email_ID lookup.
7. Error Handling
• Functional errors: If ESRI ArcGIS Field Maps or Oracle Field Service reports functional errors during query or add/update of activities or assets due to invalid parameters or invalid data, the error notification will be sent to the respective email IDs configured in the ArcGIS_OFS_Email_ID lookup.
• Remote errors: Any technical errors, such as ESRI ArcGIS Field Maps or Oracle Field Service being unavailable will cause the process to stop.
In this case:
a. An email detailing the error will be sent if the notification.email.error.flag in the OUTL-BRT-ArcGIS_OFS_ConfigProps lookup is set to ‘true’.
b. Target audience for the email is specified in the OUTL-BRT-ArcGIS_OFS_Email_ID lookup under “to”.
c. An exception will be thrown, and the Oracle Integration Cloud instance will be marked as ‘failed’.
d. After fixing the error, the flow can either be manually triggered or can wait for the next scheduled iteration.
Technical Details
The following table describes the integration processes and the respective ESRI ArcGIS Field Maps and Oracle Field Service artifacts used in this integration process.
Artifacts | Value |
|---|---|
Integration Process Name | OU OFS ArcGIS Activities Sync |
Integration Process Identifier | OUTL-BA-OFS_ARCGIS_ACTIVTY_SYNC |
Integration Project Name | OU ESRIArcGIS OFS |
Target Connection (Rest Adapter) | OU REST ArcGIS for ArcGIS-OFS |
OIC Lookups | • OUTL-BRT-ArcGIS_OFS_ConfigProps • OUTL-BRT-ArcGIS_OFS_Email_ID • OUTL-BRT-ArcGIS_OFS_AssetSearchField |
OIC Libraries | • ArcGISOFS_getSearchValFromResponse function |
Schedule Parameters
The following table describes the schedule parameters of the integration are used to Query the activities by given start date and end date.
Parameter Name | Description | Default Value |
|---|---|---|
StartDate | This parameter is used to configure the start date to query activities from OFS and ESRI. | NA |
EndDate | This parameter is used to configure the end date to query activities from OFS and ESRI. | NA |
Note: The startDate and EndDate parameters will take current date as value if the default value is set to 'NA'. Also, make sure to provide the date in the 'YYYY-MM-DD' format.
Lookups Referenced
The following table describes customized properties referenced in the integration. For more information about the lookup properties, refer to Configuring Lookups, Error Handling, and Email Notifications.
DVM | Property |
|---|---|
OUTL-BRT-ArcGIS_OFS_AssetSearchField | Configured values. |
OUTL-BRT-ArcGIS_OFS_ConfigProps | • notifcation.email.error.flag • wacs.projectedcoordinatesystem.wkid • arcgis.asset.search • ofs.activities.buckets • activity.status.include • notification.email.invalidactivities.flag |
OUTL-BRT-ArcGIS_OFS_Email_ID | • from • to |