FSM Application and Data Load Process
Purpose of the Guide
This manual provides step-by-step guidance on performing a Field Service Management deployment and foundation data loads, including:
- Setting up out-of-the-box settings for smooth functionality with custom workflow.
- Deploying the packages via the AR System Deployment management console.
Target audience
- The party doing the deployment.
Architecture
Figure 1: High Level Architecture
Items to be installed
- ARSystem forms and workflow
- Innovation Sutie Package
- Configurations including Google Maps Key
- FSM REST API Connector – docker container
- TSP API – docker container
- OpenRouteService – docker container
- OpenRouteMaps
- MobileReach Gateway
- MobileReach Client
Add Status Reasons
This is the first and foremost step to take, else the import of the installation package will fail. The following options has to be added to the various out-of-the box forms (this should preferably be done in base mode).
| Form Name | Field | Field ID | Selection Values | Alias | ID |
| AST:Attributes | StatusReason | 1000000150 | Replacement | Replacement | 6001 |
| Loan Replacement | Loan Replacement | 6002 | |||
| Loan Returned | Loan Returned | 6003 | |||
| Reserved | Reserved | 6004 | |||
| Stolen | Stolen | 96001 | |||
| Faulty | Faulty | 96002 | |||
| Dismantled | Dismantled | 96003 | |||
| Permanently Replaced | Permanently Replaced | 96004 | |||
| Backup | Backup | 96005 | |||
| Under Review | Under Review | 96006 | |||
| Damaged | Damaged | 96007 | |||
| Loan | Loan | 96008 | |||
| Retired | Retired | 96009 | |||
| WOI:WorkOrder | Status Reason | 1000000150 | Work in Progress | Work in Progress | 58001 |
| Pick-Up Stock at Warehouse | Pick-Up Stock at Warehouse | 58006 | |||
| Temp Resolution Loan Equipment Installed | Temp Resolution Loan Equipment Installed | 58007 | |||
| Sent for Repair Assessment | Sent for Repair Assessment | 58008 | |||
| Service Up | Service Up | 58009 | |||
| z1D_Work Log TypeForWorkInfoMore | 304247210 | Photos | Photos | 51100 | |
| Signatures | Signatures | 51200 | |||
| WOI:WorkInfo | Type | 1000000170 | Photos | Photos | 51100 |
| Signatures | Signatures | 51200 |
Modules & Data for Deployment
Importing the Provided Packing Lists:
In a browser, go to the following URL: http://<midtierserver>:<port>/arsys/forms/<servername>
- Log on with appropriate permissions. For more information, see BMC-Remedy-Deployment-Application-roles-and-permissions.
- Select AR System Administration > AR System Deployment Management Console.
Figure 2: AR System Deployment Management Console
- For every package provided we will repeat the following steps:
- Go to the transfer package and select Import(In the order as labeled on the packages)
- Now after all the packages are imported, we can now deploy each package in the same order as imported.
- This extracts the contents package and imports the content to BMC Remedy AR System. If the package is deployed successfully, the status of the package is updated to Deployed.
- If the are errors in you view the packages and inspect what the error is. Otherwise a rollback might need to be initiated.
Prerequisites
- Access and Administrator permissions to the server you intend to do your deployment.
- Not necessary but access to the BMC Atrium Integrator Spoon Tool (If an error occur during DMT data loads you can further access this tool to find what is causing the error.
- Latest Packing List for the FSM Application to be deployed in this order:
- 01.FSM2Rel26.2_FSM2Rel26.2_20260317.zip
Sample Data
Some Sample Data was provided, import the following
- 02.LowesCompanyData_26.2_20260317_2.zip
- 03.LowesFSMdataPackage_26.2_20260317_3.zip
Use the package manager of the ARSystem to import this pacakge as described in 3.1
Make sure you have at least 30 Fixed licenses, and 15 Floaters available on the test system before importing, elase the user records might not be created as expected.
Innovation Studio Modules
Unzip the file – Innovation Suite Files.zip
The application consists of 2 package files as described below:
- blueturtle.fsm-26.2.00-INSTALL.zip– This file consists of the custom View Components and Actions used in the Field Service Management (FSM) Application.
- com.fsm.fsm-lib-26.2.00-SNAPSHOT-INSTALL.zip -This file consists of the FSM application itself.
Installation
Login into Innovation studio.
On the Workspace, click the “Install” button
Select the library file:
Refresh and verify that the library was installed:
Repeat steps 1-4 for the application.
For configuring GoogleAPI’s , AR URL, Google Geocode URL, and SmartIT URL
From the Field Service Management Application click on Visit deployed application:
For Configuring a data source
On the Innovation Studio platform go to the Administration tab:
Go to Integrations >Data Source > Data Source Connections to add your data source(AR system) where your external records will be coming from.
Click on New and give your Data Source a name and ensure that the Type is AR System, this defines the actual data source then click next:
The Host Configuration Name and port number will be required in the next step therefore to get them you need to go to the AR system home then AR System Administration > AR System Administration Console.
Navigate to System>General>Server Information
On the Platform tab will be where the configuration name will be found.
Navigate to the Ports and Queues tab to get the server port:
On the host name, give the Host Configuration name or IP address of the environment and the port number e.g. 46262, tick the current logged in user to use the currently logged in users permissions to test the connection to the data source , and then test your connection.
You should get a successful connection.
Go to the Data source mapping to Map the application you want to apply your data source to.
Select the Field Service Management application, on the Connection configuration select the new Data source you have just configured to link the application to the data source.
After a successful mapping:
Updating settings on out-of-box forms
Work Order Status Relationships
Go to the AR Object list search for work order status relationships form http://<midtierserver>:<port>/arsys/forms:
Figure 3: AR System Object List
Figure 4: WO - Allowed Status Transitions
Check the status offline for the below settings as they originally come enabled. They should be offline just like in the above image:
- From Completed To Planning
- From Completed To In Progress
Switch off sandbox – optional but recommended
- Go to the Mid-Tier Applications and select the Application Administrator
- Go to Custom Configuration
- Go to Asset Management and Advanced
- Open the Asset Management settings to switch off the Sandbox
Figure 5: Sandbox settings
Switch off Incident Auto Assignment - Optional
- Go to the Mid-Tier Applications and select the Application Administrator
- Go to Custom Configuration
- Go to Incident Management and Advanced Options
- Select Rules and make sure the Assignment engine integration is off.
- Auto Assignment Rules to Support Group is recommended, however not agent auto assignment.
Figure 6: Incident Auto Assignment
Switch off Work Order Auto Assignment - Required
- Go to the Mid-Tier Applications and select the Application Administrator
- Go to Custom Configuration
- Go to Service Request Management and select Work Order Rules
- Make sure the Assignment Engine is off
- Assignment Rules to Support Group level is recommended.
Figure 7: Work Order Assignment
Configuring Mobile Authentication with AD
Over and above the rsso configuration, make sure the AREA LDAP Configuration is completed. If this step is not completed Authentication to the Mobile device might fail.
Google API Key
Log on to the google cloud - https://console.cloud.google.com/
Create a new API key.
Figure 8: Google Cloud Console
Please restrict the API to the following methods:
- Directions API
- Distance Matrix API
- Geocoding API
- Maps JavaScript API
We also want to restrict the IP addresses that may use the key – this is relevant for the Dispatchers only.
What IP address range will the Dispatchers use ?
This key will be used later in the installation.
Configure Settings
Open The field Service management form, go to settings and configure the environment settings.
This same configuration can also be done on the back-end as well on the form https://<your ar server>/arsys/forms/onbmc-s/FSM%3AConfig%3AServers
Navigate to FSM:Config:Servers
Figure 9: FSM:Config:Servers
Please Note : The Config name will be used in the Configuration of the various support group settings.
The test and demo optimizer server is fsmOptimizerURL is : https://fsmapi.fieldfrogs.co.za
- FSMOptimizer – This is the url used to connect to the FSM REST API Connector – the configuration of the FSM REST API Connector Docker Container is described later in this document.
- TSP Solver – This is a value that will be sent with the REST Call to access the TSP Solver, typically on another server on the sub. The configuration of the TSP Solver Docker Container is described later in this document.
- osmServerUrl – This is the url to connect to the OpenRouteService. This may be a service configured internally, url is an external server that provides a subscription service. NOTE: This server is heavily used during the route calculation, and latency to this server will slow down all route calculation and agent to site distance calculations.
- Google API Key – This key is used by the Dispatcher on his/her workstation to connect to Google maps, to display the location of Field Service agents and Sites where Work Orders have to be performed. The procedure to obtain a google api is described earlier in this document.
- Smart IT URL - Smart IT can be launched from several places in the Dispatcher console. If this configuration is not set, this action will not perform successfully.
- Dashboards URL – This has been superceded by the Dashboards Configuration later in this document. This field is not used anymore in this release.
Configure Field Service Management Settings for Support Groups
Work Order
There are some settings to be configured for auto task scheduling. These settings are done per support group.
If the support group is not filled in, then the Support Org will be used for lookup, if the Support Org is not used, the Support Company will be used for lookup, else the Global setting will be used.
The first set of settings are for the Work Order auto scheduling. Navigate to the ARSystem form ->FSM:Config:SupportGroups.
Figure 10 FSM:Config:Support Groups
Route Optimization Settings
The following settings has to be done to configure the Route Optimization.
- Use Agent Daily Start Location – Resets the route calculation that is automatically performed per support group before the workday starts. During this calculation, the Field Service Agent begins from the location specified in the CTM:People record.
- Use Agent Daily End Location – The optimizer adds the CTM:People site record as the final stop of the day when calculating the Field Service Agent’s route.
- Carry Over Unfinished Work Orders – If a Work Order is scheduled for two hours but only one hour can be completed in a day, the remaining work is carried over to the next day. The work resumes from the same location where it ended, with the remaining time allocated. This allows Work Orders to be partially completed and continued on the following day.
- Ignore Priority – If set to No, higher-priority Work Orders are scheduled before lower-priority Work Orders.
- Measurement System – Can be set to either Imperial or Metric (miles or kilometers).
- Day Start Time & End Time – These settings are currently used; however, in the next release, business hours linked to the Work Order will be used to calculate working hours for the support group. At present, the time zone specified during support group configuration is applied, but working hours are not.
- Number of Days – Defines how far into the future the optimizer schedules Work Orders. If there are more than five days’ worth of Work Orders, optimization for additional days will occur only after the first five days are completed. This value should be large enough to cover typical workloads but not too large, as higher values can slow down the route optimization API.
Landing page Dashboards
There are a number of dashboards that can be imported into the BMC Helix Dashboards on the normal way, the definitions are provided.
- Go to the dashboard to be displayed in dashboards, and select the share option, navigate to Embedded, and copy embedded iframe string
- Clean the iframe string by removing everything in yellow <iframe src="https://mobilereach-itom-dev.onbmc.com/dashboards/d-solo/e99617eb-9418-444e-8972-83f8710c93c2/geomap-of-workorders-by-request-assignee?orgId=632559010&from=1770283392818&to=1770304992818&theme=dark&panelId=3" width="450" height="200" frameborder="0"></iframe>
- Navigate to the FSM:Config:SupportGroups form, and enter the dashboard value in the first dashboard line, under the global company record.
- NOTE: Some Sample Dashboards were provided to import into Helix Dashboards.
- NOTE: There should always be at least one record in this config, for the Global company
Figure 11: FSM:Config:Support Groups - Dashboards
Make sure to add the dashboards url to the Innovation Studio iframe security settings:
Configure the following setting in the Mid-Tier to allow iframe displays for the dashboards.
Configuring Support Groups
Support Group: used to define and manage Field Service Management teams within BMC Helix IT Service Management.
Two new Support Group Roles were introduced :
- Field Services – All support groups with teams in the field using the FSM mobile app, has to be configured with this flag.
- Warehouse – All Groups managing warehouses should belong to this Role. Begin Warehouse Support Group Names with [WAR:] and the rest of the Warehouse group name after that. This prefix is required for filtering.
Add Location Data
Designated Field Service Support Group
In the demo data, we have configured the following support group for Field Services in North Carolina. Please use the agents assigned to this support group for testing purposes.
Figure 12: Configure Support Groups
PLEASE NOTE : Start from a clean machine, without the sample data. Just a clean install with Helix 26.1.02
Make sure the arsystem pods have access to the internet, to execute the optimizer API calls.
FSM MobileReach Endpoint Configuration
Overview
This guide defines the endpoint configuration for integrating the MobileReach Gateway Server with the BMC Helix platform. It ensures:
- Communication between MobileReach services and Helix applications.
- How to configure the BMC helix Platform to send push notifications to the MobileReach Gateway Server.
(This configuration sets a Soft Configuration ‘Endpoint’ setting Web Service set fields Setting on a filter level).
System Components
- MobileReach Gateway Server
- BMC Helix Platform (ITSM / Innovation Suite)
Configuration
How to configure the BMC Helix Platform to send push notifications to the MobileReach Gateway Server.
- Log on to the Mid-tier Server
| Description | Details |
Log into BMC Helix Server with administrator credentials navigate to FSM:MobileReach:Config form. | http://<HostPort>/arsys/forms/<ARserver>/FSM%3AMobileReach%3AConfig/ |
 | |
When creating, the following Fields must be Completed for the Gateway Configuration:
|
|