International Mapping - ArcGIS Configurable App

This application is written in TypeScript and utilizes @esri/templates-common-library, @esri/configurable-app-components, @esri/calcite-components to create an out-of-the-box configurable mapping application.

Developer quickstart

• npm start - Development server. Outputs to ./output/dev
• npm run build - Production build. Outputs to ./output/dist
• npm run lint - Lint and fix code.

Configuration

Most ApplicationConfig properties can be passed in as URL parameters.

interface ApplicationConfig {
    appid?: string;
    center?: string;
    components?: string;
    embed?: boolean;
    extent?: string;
    find?: string;
    group?: string | string[];
    helperServices?: any;
    level?: string;
    marker?: string;
    oauthappid?: string;
    portalUrl?: string;
    proxyUrl?: string;
    title?: string;
    viewpoint?: string;
    webmap?: string | string[];
    webscene?: string | string[];
    [propName: string]: any;
}

interface ApplicationBaseSettings {
    localStorage?: {
        fetch?: boolean;
    };
    group?: {
        default?: string;
        itemParams?: PortalQueryParams;
        fetchItems?: boolean;
        fetchInfo?: boolean;
        fetchMultiple?: boolean;
    };
    portal?: {
        fetch?: boolean;
    };
    urlParams?: string[];
    webMap?: {
        default?: string;
        fetch?: boolean;
        fetchMultiple?: boolean;
    };
    webScene?: {
        default?: string;
        fetch?: boolean;
        fetchMultiple?: boolean;
    };
}

Deployment to Portal (ArcGIS Online)

This setup is compatible with both ArcGIS Online and Portal for ArcGIS.

The following directions are using the ArcGIS REST API but you can also do each of these steps in the Portal user interface.

Before you attempt to deploy to Portal you should already have the application hosted on a web server. The location of where you've hosted the built application will be referred to as {appURL}.

You will need an access token to make each request. We will refer to the base Portal as {portalURL} and the access token as {token}. If you are using ArcGIS Online, your {portalURL} is: https://www.arcgis.com

Create template item

ESRI Documentation: Add your template to the Portal or Add your template to ArcGIS Online, Create a configuration file

There will only ever be one of these per organization. This item will be re-used by child applications. The template item holds the "configuration settings" which will control what settings each deployed application will have such as webmap/webscene, theming/colors, etc. This configuration exists on the "data" attribute of the item in Portal

Notice: The url of this item is required, but irrelevant. The data field is the JSON configuration of the item. You can set this when you create the item or simply update the JSON configuration in Portal after you've created the item.

We will refer to this item as {templateItem}.

ArcGIS REST API: Add item

https://{portalURL}/sharing/rest/content/users/{username}/{folderId}/addItem

{
  "title": "WebScene App",
  "type": "Web Mapping Application",
  "typeKeywords": "Web Map, Map, Online Map, Mapping Site, JavaScript, Configurable",
  "thumbnailURL": "https://static.arcgis.com/images/webapp.png",
  "url": "{appURL}",
  "tags": "ArcGIS web application template, express setup, instant apps, instant mapping apps, 4.x, 3Dscene"
  "data": "{SEE FILE ./src/config/applicationConfig.json}"
  "f": "json",
  "token": "{token}"
}

{
  "success":true,
  "id":"{templateItem}",
  "folder": "{folderId}"
}

Register template item app id

And you'll need to register this app to get an OAuth2 app id, client id, and client secret. The {appURL} in this instance is very important since it is used for authentication against Portal. Any URL the application will be accessed (public or private) needs to be added to Redirect URI's. This is easy to do in Portal.

ArcGIS REST API: Register App

https://{portalURL}/sharing/rest/oauth2/registerApp

{
  "itemId": "{templateItem}",
  "appType": "browser",
  "redirect_uris": ["{appURL}"]
  "f": "json",
  "token": "{token}"
}

{
  "itemId":"{templateItem}",
  "client_id":"{clientId}",
  "client_secret":"{clientSecret}",
  "appType":"browser",
  "redirect_uris":["{appURL}"],
  "registered":1607445762000,
  "modified":1607445762000,
  "apnsProdCert":null,
  "apnsSandboxCert":null,
  "gcmApiKey":null,
  "httpReferrers":[],
  "privileges":[]
}

Create template group for organization

Once the template exists, it needs to be shared into the organization's template group. We will refer to this group as {templateGroupId}.

By default the template group is defined by ESRI and is not a group you can share items into. In this case a group must be created and the organization's settings updated. If the organization already has a custom template group configured, this step can be skipped.

TO BE CONTINUED...

Share template item

Share the {templateItem} with your organization and your {templateGroupId}.

ArcGIS REST API: Share Item (as item owner)

https://{portalURL}/sharing/rest/content/items/{templateItem}/share

{
  "items": "{templateItem}",
  "org": true,
  "groups": "{templateGroupId}",
  "f": "json",
  "token": "{token}"
}

Deploy an application

Deploying a new application with the template item is very easy and can be done within Portal.

Create application item

ArcGIS REST API: Add item

https://{portalURL}/sharing/rest/content/users/{username}/{folderId}/addItem

{
  "title": "My New App",
  "type": "Web Mapping Application",
  "typeKeywords": "Configurable, Map, Mapping Site, Online Map, Web Map",
  "thumbnailURL": "https://static.arcgis.com/images/webapp.png",
  "url": "{appURL}?appid=",
  "tags": "Development",
  "data": {
    "source": "{templateItem}",
    "values": {
      "theme": "white",
      "labelLayers": [],
      "slides": []
    }
  },
  "f": "json",
  "token": "{token}"
}

{
  "success":true,
  "id":"{appId}",
  "folder": "{folderId}"
}

Update application item URL

After the item has been created you need to update the url of the item to include the newly created {appId}.

ArcGIS REST API: Update item

https://{portalURL}/sharing/rest/content/users/{username}/items/{appId}/update

{
  "url": "{appURL}?appid={appId}"
  "f": "json",
  "token": "{token}"
}

Remember {appURL} is where you've hosted the built version of the application. To view your application visit:

https://{appURL}/?appId={appId}

Share application item

You'll want this item to be shared with your organization, or share it publicly if it will be a publicly accessible application.

ArcGIS REST API: Share Item (as item owner)

https://{portalURL}/sharing/rest/content/items/{templateItem}/share

{
  "items": "{appId}",
  "org": true,
  "f": "json",
  "token": "{token}"
}

You're done!

You can configure your new app at:

https://{portalURL}/home/webmap/configureApp.html?folderid={folderId}&appid={appId}

Resources

• @esri/templates-common-library/baseClasses/support/configParser
• https://github.com/Esri/templates-common-library/blob/master/src/baseClasses/support/urlUtils.MD
• https://github.com/Esri/templates-common-library/blob/master/src/baseClasses/support/itemUtils.MD
• https://github.com/Esri/templates-common-library/blob/master/src/baseClasses/support/domHelper.MD
• @esri/templates-common-library/a11yUtils.ts - setupLiveRegion
• @esri/templates-common-library
• @esri/application-base-js: ApplicationBase
• Esri/configurable-app-examples-4x-js
• https://developers.arcgis.com/javascript/latest/sample-code/widgets-custom-widget/#register-the-message-bundle

Portal for ArcGIS

• Portal for ArcGIS: Add configurable parameters to templates

ArcGIS Online

• Create configurable app templates
• Create configurable app templates
• Register the app template/Add your template to ArcGIS Online
• Making your app configurable
• Example configuration file
• Associate the configuration information with the template item
• Creating and publishing your own configurable apps
• Configure search in apps

Deprecated Configurable Apps

• https://github.com/Esri/templates-common-library/blob/master/src/baseClasses/CompatibilityChecker.ts#L8
• https://github.com/Esri/application-base-js
• https://github.com/Esri/configurable-app-examples-4x-js
• https://github.com/Esri/filter-gallery
• https://github.com/Esri/zone-lookup
• https://github.com/Esri/interactive-legend
• https://github.com/Esri/media-template
• https://github.com/Esri/attachment-viewer
• https://github.com/Esri/minimalist
• https://github.com/Esri/minimalist/blob/master/minimalist/app/utils/esriWidgetUtils.ts