Deploy Workforce

You can help mobile users and dispatchers get started with ArcGIS Workforce in the following ways:

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
Parameter and value pairs are replaced with the values you want to use to deploy the app. For example, the following link uses the parameter portalURL to take mobile users directly to the sign-in screen for your organization and prompts them to sign in:
  • 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).

ParameterValuesNotes

portalURL

Your organization's portal URL

  • If specified and the mobile user is signed out or connected to a different portal (including ArcGIS Online), they are prompted to sign out and then 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 of the assignment to open in Workforce

  • Requires mapID.
  • The GlobalID of an assignment is found on the Data tab on the item page for the Assignments layer. When looking at 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.
  • The following integer values are supported:
    • 1 (Assigned)
    • 2 (In Progress)
    • 3 (Completed)
    • 4 (Declined)
    • 5 (Paused)

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

Download 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=Esri
Note:

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.

ParameterValuesNotes

assignmentType

The assignment type given to an assignment.

  • You can use the GlobalID 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 lon.

lon

The x-coordinate of the assignment in WGS84 (WKID: 4326).

  • Requires lat.

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 of the worker or their user name.
    Note:

    If you are creating a link for a Classic project, the objectid or user name can be used.

  • Values are not case sensitive.
Note:

All parameters are optional; however, the assignmentType, lat, lon, and location fields must be filled in 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 field.

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:

KeyValueNotes

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 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.