Register Item (Data Stores) | ArcGIS REST APIs

URL:: https://<root>/data/registerItem
Methods:: POST
Version Introduced:: 10.9

Access requirements

Required privileges

The Enterprise Administrator API requires privilege-based access. An administrator must be assigned a specific user privilege, or role, to access any given endpoint. Listed below are the user privileges or roles an administrator can be assigned that provides access to this endpoint. If multiple privileges are listed, only one needs to be assigned to gain access.

Publisher role Update

Tokens

This API requires token-based authentication. A token is automatically generated for administrators who sign in to the Enterprise Administrator API directory's HTML interface. Tokens generated in this way are stored for the entirety of the session.

Those accessing the API directory outside of the HTML interface will need to acquire a session token from the generateToken operation in the Enterprise Directory API. For security reasons, all POST requests made to the Enterprise Administrator API must include a token in the request body.

Learn how to generate a token

Description

The registerItem operation registers a new data item (for example, geodatabases, cloud shares, and file shares) with a data store. Before registering the data item, you must validate it and ensure that it is accessible.

Request parameters

Parameter	Details
`item`	The JSON representation of the data item. Starting with ArcGIS Enterprise on Kubernetes 10.9.1, specific user-defined information must be provided to register new folder paths in a deployment. For more information, see the User-managed store properties section below. Example Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 item={ "clientPath": "\\\\sample_server\\SharedPath\\Data", "type": "folder", "info": { "fileServerHost": "nfsHost.example.com", "fileServerType": "nfs", "fileServerPath": "/SharedPath/Data" } }`
`options` (Optional; required for new file share locations)	Introduced at 11.0. A JSON array of additional properties used during registration. Currently, only the `allowServicesRestart` property is supported. Adding a new file share location requires the pods for all system and utility services to restart, as well as restarting the shared pods for map and tile services. Affected services will be unavailable during this time and may take some time before they are once again available. By setting `allowServicesRestart` to `true`, administrators are acknowledging that registering a new file share location will disrupt their organization. Not providing `allowServicesRestart`, or setting it to `false`, will cause the registration of the new file share location to fail. Note This parameter is not required if you are registering an extension of a previously registered path with the organization: Examples Use dark colors for code blocksCopy `1 2 3 4 5 6 7 //Example one: a new path. Requires allowServicesRestart to be set to true and services will restart /myshare/folder1 //Example two: an extension to the path (above) that was previously registered. Does not require allowServicesRestart to be set to true, and services will not restart /myshare/folder1/subfolder2/subfolder3` Example Use dark colors for code blocksCopy `1 options={"allowServicesRestart": true}`
`async` (Optional)	Introduced at 11.0. This parameter specifies whether the operation will run synchronously or asynchronously. If `false`, the operation is run synchronously. If `true`, the operation is run asynchronously and the response returns a JSON object containing job information that can be used to track the job's status. The default value is `false`. Values: `true` \| `false`
`f`	The response format. The default response format is `html`. Values: `html` \| `json` \| `pjson`

User-managed store properties

Root paths for user-managed folder data stores can be registered using Network File Sharing (NFS) folders or, starting with 11.5, persistent volumes (PVs). Specific user-defined information must be provided for registration depending on what is used to back the folder data store.

The following sections provide JSON examples for the item parameter for each supported option.

For all NFS folder-based stores, the following user-defined information must be provided:

clientPath: Either a drive or shared location where source data can be accessed and published by clients, such as ArcGIS Pro. If the clientPath value is a drive location, the hostName property must be included as well.
fileServerHost: The machine name where shared data is stored and can be accessed through an NFS path.
fileServerPath: An NFS path on the host machine where shared data can be accessed across the organization.

The tabs below provide sample JSON objects for the item parameter for NFS folder data stores.

The following is a sample JSON object for an NFS folder data store at a shared location:

Example
Use dark colors for code blocksCopy
{
  "clientPath": "\\\\sample_server\\SharedPath\\Data",
  "type": "folder",
  "info": {
    "fileServerHost": "nfsHost.example.com",
    "fileServerType": "nfs",
    "fileServerPath": "/SharedPath/Data"
  }
}

The following is a sample JSON object for an NFS folder data store at a local drive location:

Example
Use dark colors for code blocksCopy
{
  "clientPath": "C:\\data",
  "type": "folder",
  "info": {
    "fileServerHost": "nfsHost.example.com",
    "fileServerType": "nfs",
    "fileServerPath": "/data",
    "hostName": "yourclienthost.example.com"
  }
}

Persistent volume (PV)

Starting with ArcGIS Enterprise for Kubernetes 11.5, you can use PVs to back folder data stores to allow different kinds of storage options such as local directories (using local PVs) for increased service performance and Windows shares. To learn more about using PVs, see Manage data stores.

The tabs below provide sample JSON objects for the item parameter for PV-based folder data stores.

The following is a sample JSON object for a PV-based Windows share:

Example
Use dark colors for code blocksCopy
{
  "clientPath": "\\\\SampleWindowsServer\\Path\\Data",
  "type": "folder",
  "info": {
    "volumeType": "PVC",
    "volumeAttachMode": "GLOBAL",
    "volumeIdentifier": "", // OPTIONAL
    "volumePath": "//SampleWindowsServer/Path/Data",
    "volumeSpec": {
      "accessModes": [
        "ReadOnlyMany"
      ],
      "volumeMode": "Filesystem",
      "resources": {
        "requests": {
          "storage": "100Gi"
        }
      },
      "storageClassName": "", // OPTIONAL
      "volumeName": "windows-pv"
    }
  }
}

The following is a sample JSON object for a PV-based NFS share:

Example
Use dark colors for code blocksCopy
{
  "clientPath": "\\\\SampleNFSServer\\Path\\Data",
  "type": "folder",
  "info": {
    "volumeType": "PVC",
    "volumeAttachMode": "GLOBAL",
    "volumeIdentifier": "nfsHost.example.com",
    "volumePath": "//SampleNFSServer/Path/Data",
    "volumeSpec": {
      "accessModes": [
        "ReadOnlyMany"
      ],
      "volumeMode": "Filesystem",
      "resources": {
        "requests": {
          "storage": "100Gi"
        }
      },
      "storageClassName": "", // OPTIONAL
      "volumeName": "nfs-pv"
    }
  }
}

The following is a sample JSON object for a local PV-based folder data share:

Example
Use dark colors for code blocksCopy
{
  "clientPath": "\\\\SampleServer\\Path\\RoutingData",
  "type": "folder",
  "info": {
    "dataStoreConnectionType": "replicated",
    "volumeType": "PVC",
    "volumeAttachMode": "DEDICATED",
    "volumeIdentifier": "", // OPTIONAL
    "volumePath": "//SampleServer/Path/RoutingData",
    "volumeSpec": {
      "accessModes": [
        "ReadWriteOnce"
      ],
      "volumeMode": "Filesystem",
      "resources": {
        "requests": {
          "storage": "100Gi"
        }
      },
      "storageClassName": "local-storage",
      "volumeName": "local-pv"
    }
  }
}

Example usage

The following is a sample POST request for the registerItem operation:

Use dark colors for code blocksCopy
POST /<context>/admin/data/registerItem HTTP/1.1
Host: organization.example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

item={
  "clientPath": "\\\\sample_server\\SharedPath\\Data",
  "type": "folder",
  "info": {
    "fileServerHost": "nfsHost.example.com",
    "fileServerType": "nfs",
    "fileServerPath": "/SharedPath/Data"
  }
}&options={"allowServicesRestart": true}&async=false&f=pjson&token=uH1XErH8KruWpIAJId4WJ1tfR0xuolWt4bz5S58vYqk5qpbDhGnpbbysmiVDyqDf70tr6i0n4qYCql7eZa_PiKgnA2-1ccEB2O4rkymYoc0-R4WnYrO_t_7Rm9qKzVLN7oFDmJpqmCt55mKz3WyQkumnK2MmBYmgYmU2DycSPyKL4BJx0gr1UHmfqeWA7I52zBsgV8FiND6e_AhjzktIwF8iifMg96Hm0KAGztgsdSDQF0tvLj7doyxTQFWuGRik

JSON Response examples

If async is false, the following response is returned:

Use dark colors for code blocksCopy
{"status": "success"}

If async is true, the following response is returned. The value returned for jobsUrl can be used to access the job resource to track a job's status after it's been submitted. For more information, see the Job resource topic.

Use dark colors for code blocksCopy
{
  "jobsUrl": "https://organization.example.com/<context>/admin/jobs/ja2ca1a35-881c-400c-a49a-b26883002d6c",
  "jobID": "ja2ca1a35-881c-400c-a49a-b26883002d6c",
  "jobStatus": "SUBMITTED"
}