Recompile Custom Data Providers in 12.0

This is a special topic intended for helping developers and administrators recompile any unsupported custom data providers that did not get automatically re-registered when upgrading from ArcGIS Enterprise 11.x to ArcGIS Enterprise 12.0 and restarting stopped services. Not every step may apply to your situation, so carefully read each step in the guide. The end of this guide contains a full example of migrating the Yelp data provider from 11.x to 12.0. Each step in the guided walkthrough is illustrated in the example.

Guided walkthrough

Step 1. Replace the config module and /config/default.json

1. Ensure that the npm module config is not in your list of dependencies in the provider's package.json file. The file location is /providers/provider-name/package.json. If the config dependency is present in /providers/provider-name/package.json, then from the /providers/provider-name/ folder, run npm uninstall config.
2. Create a new JSON file that will replace the functionality of the deprecated /config/default.json file. For ease of reference, this file can be placed in providers/provider-name/src/ directory. Give this JSON configuration file any name of your choosing.
   • If your previous, unsupported provider did not make use of the /config/default.json file (i.e. it was just an empty object), then you do not need to create a new JSON configuration file. You can skip steps 1.3 and 1.4 and move to Step 2.
3. Copy over the exact contents of the previous default.json file to the new JSON configuration file.
4. Now require this file in your model.js and in any other files that referenced "config". For instance if your model.js file has the line at the top: const config = require("config"); then replace it with const config = require(./<my-new-config-name>.json);. As long as your variable is named the same and you copied over the original default.json exactly, this should work seamlessly.

Step 2. Replace host and id with service parameters

1. If you are using the host property in your unsupported provider, in the /providers/provider-name/cdconfig.json file create an object in the properties.serviceParameters array with the properties key, label, and description. If you are also using id in your old provider, create another object in the properties.serviceParameters array.

   • If your previous, unsupported provider did not make use of the host and id parameters, then you do not need to create any objects in the serviceParameters array. You can skip steps 2.2, 2.3, and 2.4 and move to Step 3.

2. Provide a value for key that you will use to access the parameter in your code. It is best to use snake or camel case. Provide a value for label that will show up in user interfaces such as ArcGIS Portal Home and Enterprise Manager. Provide a value for description that will show up in user interfaces such as ArcGIS Portal Home and Enterprise Manager and will clearly describe the parameter. Click here for more details on service parameters.

3. Update your model.js code in the places where you previously referenced host and/or id. For instance if you had the line const dbTableName = req.params.host, the replacement line would be const dbTableName = req.params.<my-new-key-value>. Parameter values are accessed on the req.params object as before.

4. Test your code in the development environment. Refer to the topic on service parameters for testing information. Export the new provider as a .cpdk file, and register it with ArcGIS Server.

Step 3. Update the service JSON

1. In the ArcGIS Sever Administrator Directory, go to Home > service > nameOfStoppedService.FeatureServer > edit.
2. Locate the section of service JSON called customDataProviderInfo.
   • If customDataProviderInfo contains a key called forwardUserIdentity leave its value as is. If it does not, there is no need to add the key.
   • Delete the keys dataProviderHost and dataProviderId. Add an empty object called serviceParameters.
   • If your custom data provider does not make use of any service parameters, then save the edits and restart the service. Your upgrade for this service is complete.
3. If your custom data provider uses service parameters, add them to the serviceParameters object as follows: "serviceParameters": {"key1": "value", "key2": "value", "key3": "value"}. Restart the service. Your upgrade for this service is complete.

Yelp data provider example

This example will illustrate all the steps above by showing all the code changes required to upgrade the Yelp data provider.

Replacing the config module and /config/default.json

• The package.json no longer contains the config module in the dependencies.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "name": "yelp-data-provider",
  "version": "11.4.0",
  "description": "Template for customdata provider",
  "main": "src/index.js",
  "scripts": {
    "test": "mocha 'test/**/*.test.js'",
    "start": "node src/index.js"
  },
  "dependencies": {
    "config": "^3.2.5",

• The configuration JSON was copied from /default/config.json to yelp-data-config.json.

1
2
3
4
5
{
  "yelp": {
    "apiKey": "<API KEY>"
  }
}

• On line 1 of the model.js file, the Yelp configuration file is now 'required in' rather than referencing the config module.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
const config = require("config");
const parseGeoJSON = require("./parseGeoJSON");
const yelp = require("yelp-fusion");
const yelpClient = yelp.client(config.yelp.apiKey);
function Model() {}
Model.prototype.getData = function (req, callback) {
  const host = req.params.host;
  const id = req.params.id;
  yelpClient
    .search({
      categories: host,

Replacing host and id with service parameters

• The boilerplate cdconfig.json no longer contains the properties hosts and disableIdParam when creating a provider in the 12.0 SDK.
• The boilerplate cdconfig.json contains an empty serviceParameters array. The two parameters category and city were added to replace the old host and id.

1
2
3
4
5
6
7
8
9
10
11
12
{
  "name": "yelp-data-provider",
  "arcgisVersion": "11.4.0",
  "parentServiceType": "FeatureServer",
  "customdataRuntimeVersion": "1",
  "type": "provider",
  "properties": {
    "hosts": true,
    "disableIdParam": false
  },
  "fileName": "yelp-data-provider.cdpk"

• Each instance of the use of host and id has been updated in model.js to use category and city.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
const config = require("config");
const parseGeoJSON = require("./parseGeoJSON");
const yelp = require("yelp-fusion");
const yelpClient = yelp.client(config.yelp.apiKey);
function Model() {}
Model.prototype.getData = function (req, callback) {
  const host = req.params.host;
  const id = req.params.id;
  yelpClient
    .search({
      categories: host,

Updating the service JSON

• The customDataProviderInfo object contains an optional key called forwardUserIdentity that was introduced at ArcGIS Enterprise 11.5. Click here to read more about the forwardUserIdentity property.
• The keys dataProviderHost and dataProviderId are no longer included.
• The serviceParameters object must contain all keys defined in the provider's cdconfig.json file, and values must be provided for each of these keys.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "serviceName": "yelpRedlands",
  "jsonProperties": {
    "customDataProviderInfo": {
      "dataProviderName": "yelp-data-provider",
      "dataProviderHost": "restaurants",
      "dataProviderId": "redlands"
    }
  },
  "type": "FeatureServer",
  "description": "",