You can help mobile users and dispatchers get started with ArcGIS Workforce in the following ways:
- Provide a link for mobile users that can be used to install the app, set the portal URL, download the map, open an assignment, or set the status of an assignment.
- Provide a link for dispatchers that can be used to streamline assignment creation.
- Use mobile device management (MDM) software to deploy and configure the mobile app, including the portal URL.
Open the Workforce mobile app from a link
Mobile users can specify their portal URL in Workforce, or you can provide a URL directly to them that specifies the correct portal URL. Make it easy for your mobile users to access the correct portal by sharing a link through an email, text message, web page, QR code, or another app. When tapped, Workforce opens to the portal URL you want the mobile worker to use.
Link structure
Links to the Workforce mobile app have the following format:
- https://workforce.arcgis.app?parameter=value
- https://workforce.arcgis.app?portalURL=https://myportal.mycompany.com/arcgis
Parameters
The following parameters are supported with Workforce links. If no parameters are passed, tapping the link opens Workforce (or prompts you to download the app).
| Parameter | Values | Notes |
|---|---|---|
portalURL | Your organization's portal URL |
|
mapID | The item ID of the map to download and open in Workforce |
|
assignmentID | The GlobalID of the assignment to open in Workforce |
|
assignmentStatus | The status given to an assignment when opened in Workforce |
|
Continue reading for examples of using these parameters to achieve specific behavior with a Workforce link.
Connect to a specific portal
Specify the URL of the portal the mobile worker should be connected to.
The following is an example:
https://workforce.arcgis.app?portalURL=https://myportal.mycompany.com/arcgisDownload and open a map
Download and open a map using the mapID parameter. If the mobile worker already has the map downloaded on their device, no download occurs, and the specified map is opened in Workforce.
The following are examples:
- Open the map as the currently signed-in mobile worker, or if not signed in, provide the opportunity for them to sign in:
https://workforce.arcgis.app?mapID=3ac4145c1ac44aea86e9ed42e00fbb0d - Connect to a particular portal and then open the map:
https://workforce.arcgis.app?portalURL=https://myportal.mycompany.com/arcgis&mapID=3ac4145c1ac44aea86e9ed42e00fbb0d
Open an assignment
Open an assignment in the map using the assignmentID parameter.
The following is an example:https://workforce.arcgis.app?mapID=3ac4145c1ac44aea86e9ed42e00fbb0d&assignmentID=948b2bf3-f866-4516-97e7-00418d3b567d
Set the status of an assignment
Set the status of an assignment using the assignmentStatus parameter.
The following is an example:https://workforce.arcgis.app?mapID=3ac4145c1ac44aea86e9ed42e00fbb0d&assignmentID=948b2bf3-f866-4516-97e7-00418d3b567d&assignmentStatus=2
Note:
It is possible, but not advised, to use this parameter to set the assignment status in ways that aren't possible in the mobile app. For example, if an assignment has a status of Assigned, a Workforce link can be used to set it to Paused, skipping the In Progress status that would be set by the mobile worker. Skipping this status isn't possible in the mobile app.
Open the Workforce web app from a link
You can streamline deployment of the Workforce web app by sharing a link through an email, text message, web page, QR code, or another app. Links can be customized with URL parameters to open an existing assignment or a new assignment with assignment information already populated.
Providing a link to dispatchers allows them to create assignments that already have key information filled in. For example, if you want to create assignments from a third party app, you can include a link that automatically populates the location, description, and due date of a new assignment.
Link structure
Links to the Workforce web app always begin with the following format:
- http://<portal-url>/apps/workforce/projects/<project-id>
To open a specific assignment, append /dispatch/assignments/<assignment-id> to the link:
- http://<portal-url>/apps/workforce/projects/<project-id>/dispatch/assignments/<assignment-id>
To launch the creation of a new assignment, append /dispatch/assignments/new? to the link and include one or more parameters separated by an ampersand (&):
http://<your portal url>/apps/workforce/projects/<project-id>/dispatch/assignments/new?assignmentType=repair&lat=34.057170&lon=-117.194150&location=EsriNote:
The project-id can be found in the URL when the Workforce project is open. For example, if the URL is http://arcgis.com/apps/workforce/projects/a0f297f949f549f0ade07eee562d9934, the project-id is a0f297f949f549f0ade07eee562d9934.
Encode the parameters
All parameters in links to the Workforce web app must be encoded. Encoding replaces invalid characters with % followed by their hex equivalent.
For example, the following link has unencoded parameters:http://<portal-url>/apps/workforce/projects/<project-id>/dispatch/assignments/new?assignmentType=repair hydrant&lat=34.057170&lon=-117.194150&location=Esri Campus
Here is the same link with encoded parameters:http://<portal-url>/apps/workforce/<project-id>new?assignmentType=repair%20hydrant&lat=34.057170&lon=-117.194150&location=Esri%20Campus
There are many free websites and tools for generating encoded URLs. For example, Albion Research Ltd. has a URLEncode and URLDecode Page.
Create an assignment
Create a link that launches the Workforce web app with assignment information already populated for a new assignment. For example, if you have a custom app for creating tree inspections, you can create a link that opens Workforce with the assignment type and location information already filled in for a new tree inspection assignment.
Parameters
The parameters listed below are supported for creating assignments with Workforce links.
| Parameter | Values | Notes |
|---|---|---|
assignmentType | The assignment type given to an assignment. |
|
lat | The y-coordinate of the assignment in WGS84 (WKID: 4326). |
|
lon | The x-coordinate of the assignment in WGS84 (WKID: 4326). |
|
location | The location text used for the assignment. |
|
priority | The priority given to an assignment. |
|
duedatetime | The due date and time given to an assignment. |
|
workorderid | A key referencing a work order from an external or third-party system. |
|
description | Information about the assignment. |
|
assignee | The user assigned to the assignment. |
|
Note:
All parameters are optional; however, the assignmentType, lat, lon, and location fields must be filled in before the new assignment can be created.
Examples
The following are examples of how parameters can be used within an app link to populate information when creating a new Workforce assignment:
- Create an assignment using coordinates:
http://<portal-url>/apps/workforce/projects/<project-id>/dispatch/assignments/new?lat=34.057170&lon=-117.194150 - Create a tree inspection assignment with a medium priority level and assign it to a mobile worker:
http://<portal-url>/apps/workforce/projects/<project-id>/dispatch/assignments/new?assignmentType=inspect%20tree&lat=34.057170&lon=-117.194150&location=esri&priority=2&assignee=mobile_worker - Create a pipe repair assignment that's due on May 23 at 3:00 p.m.:
http://<portal-url>/apps/workforce/projects/<project-id>/dispatch/assignments/new?assignmentType=pipe%20repair&lat=34.057170&lon=-117.194150&location=esri&duedatetime=1621782000000 - Create a repair assignment with a description of the problem:
http://<portal-url>/apps/workforce/projects/<project-id>/dispatch/assignments/new?assignmentType=repair&&lat=34.057170&lon=-117.194150&location=esri&description=Repair%20the%20valve.
Mobile device management
Mobile device management (MDM) refers to software used for the administration of mobile devices in an organization. An MDM is used to enhance data and network security as well as to set and enforce mobile device policies. Additionally, using an MDM increases the efficiency of app deployments and management for mobile devices, including controlling how and when an app is updated. To learn more about how Esri approaches MDM, see ArcGIS Secure Mobile Implementation Patterns in the ArcGIS Trust Center.
When preparing to deploy Workforce to your organization's mobile devices via MDM, there are some application and profile settings you may want to configure. These include portal URL and per-app VPN settings.
Caution:
If you're using an Android device, Chrome or another browser must be installed and enabled to display the portal sign-in screen.
Workforce app configuration
App configuration (also referred to as AppConfig) refers to a format for providing application settings such as the portal URL. Instead of configuring these settings manually each time a mobile app is installed, you can use your MDM to specify and apply app configurations automatically. These settings are defined as a dictionary of key-value pairs in an XML file. How the dictionary is created depends on the MDM you're using. To learn more about app configuration, visit the AppConfig Community.
Workforce has the following settings that can be implemented with app configuration in your MDM:
| Key | Value | Notes |
|---|---|---|
portalURL | Your organization's portal URL |
|
Per-app virtual private network
Configuring a per-app virtual private network (per-app VPN) in your MDM allows you to restrict access to internal resources to specific managed apps. Workforce can be deployed with this configuration. To set up per-app VPN for use with Workforce, see the software documentation for the MDM you are using.
Caution:
If you're on iOS, Safari is used to display the portal sign-in screen in Workforce. For this to work correctly with a per-app VPN enabled, your portal domain (for example, mycompany.com) must be specified in the Safari Domains setting in the per-app VPN profile you're using. If Safari Domains is not set correctly, the assigned mobile devices cannot access the Workforce portal sign-in screen.
When you set a Safari Domain in the per-app VPN profile as described above, the Safari Browser can also access the portal domain you specified in the Safari Domains. If you want to block this access, configure an iOS Restriction (if available in your MDM) to Block Safari Browser App on the desired devices.
After you've configured the per-app VPN settings for Workforce in your MDM, when the app is launched on a managed mobile device, it automatically connects to the designated per-app VPN. When Workforce is running in the background, the per-app VPN is still connected, but only to Workforce. When Workforce is closed, the mobile device automatically disconnects from the per-app VPN.