Deploy Workforce

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, and 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. Allow 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. Parameter and value pairs are replaced with the values you want to use to deploy the app. For example, the https://workforce.arcgis.app?portalURL=https://myportal.mycompany.com/arcgis link uses the portalURL parameter to take mobile users directly to the sign-in screen for your organization and prompts them to sign in.

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	If a value is specified and the mobile user is signed out or connected to a different portal (including ArcGIS Online), they are prompted to sign out and taken directly to the sign-in screen for your organization and prompted to sign in. Provide the same URL you enter in the browser when you want to access the portal, for example, https://myportal.mycompany.com/arcgis.
mapID	The item ID of the map to download and open in Workforce	The item ID is in the URL of the item page for the Worker map. For example, if the item page URL of the Worker map is https://www.arcgis.com/home/item.html?id=fc60dfd46b234fbeaa74e76e6b17fb7b, the item ID of the map is fc60dfd46b234fbeaa74e76e6b17fb7b.
assignmentID	The GlobalID value of the assignment to open in Workforce	Requires a mapID value. The GlobalID value of an assignment is found on the Data tab on the item page for the Assignments layer. In the table, click the Options menu and click Show/Hide Columns. Select GlobalID to display this value for each assignment.
assignmentStatus	The status given to an assignment when opened in Workforce	Requires mapID and assignmentID values. The following integer values are supported: 1 (Assigned) 2 (In Progress) 3 (Completed) 4 (Declined) 5 (Paused)

Examples of using these parameters to achieve specific behavior with a Workforce link are provided below.

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/arcgis

Download and open a map

Download and open a map using the mapID parameter. If the mobile worker 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 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 have key information filled in. For example, 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 an 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=Esri

Note:

The project-id value 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 value is a0f297f949f549f0ade07eee562d9934.

Encode the parameters

All parameters in links to the Workforce web app must be encoded. Encoding replaces invalid characters with the percent sign (%) 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

The following 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 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	You can use the GlobalID value or the name of the assignment type. Note: If you are creating a link for a Classic project, the coded value domain or assignment type name can be used. Values are not case sensitive.
lat	The y-coordinate of the assignment in WGS84 (WKID: 4326)	Requires a lon value.
lon	The x-coordinate of the assignment in WGS84 (WKID: 4326)	Requires a lat value.
location	The location text used for the assignment	This parameter is ignored if lat and lon aren't populated.
priority	The priority given to an assignment	The following integer values are supported: 0 (None) 1 (Low) 2 (Medium) 3 (High) 4 (Critical)
dueDateTime	The due date and time given to an assignment	In numerical milliseconds since the Unix epoch.
workOrderId	A key referencing a work order from an external or third-party system	A value from your external system.
description	Information about the assignment	Explanatory text.
assignee	The user assigned to the assignment	You can use the GlobalID value of the worker or their username. Note: If you are creating a link for a Classic project, the objectid value or username can be used. Values are not case sensitive.

Note:

All parameters are optional; however, the assignmentType, lat, lon, and location parameters must be populated before the new assignment can be created.

If you're using ArcGIS Enterprise, lat and lon are the only supported parameters when creating an assignment from a link. The Workforce web app on ArcGIS Enterprise uses reverse geocoding to populate the location parameter.

Examples

The following are examples of how parameters can be used in an app link to populate information when creating a 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 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 through MDM, there are some application and profile settings you can 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 an 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 web page.

Workforce has the following settings that can be implemented with app configuration in an MDM:

Key	Value	Notes
portalURL	Your organization's portal URL	When Workforce is launched, it skips directly to the sign-in screen for your organization's portal. For example, https://myportal.mycompany.com/gis. The value type is string.

Per-app virtual private network

Configuring a per-app virtual private network (per-app VPN) in an 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 Domains value in the per-app VPN profile as described above, the Safari browser can also access the portal domain you specified in Safari Domains. To block this access, configure iOS Restriction (if available in the MDM) to use Block Safari Browser App on the applicable devices.

Once you configure the per-app VPN settings for Workforce in the MDM, the app automatically connects to the designated per-app VPN when the app is opened on a managed mobile device. When Workforce is running in the background, the per-app VPN is only connected to Workforce. When Workforce is closed, the mobile device automatically disconnects from the per-app VPN.