Configure a Custom Map Layer by Using the Metadata API

You can use Metadata API to configure custom map layers on a map. A map layer is a collection of objects that you can add to a map to designate common associations related to company assets, such as network nodes, underground infrastructure, warehouses, and so on. You can also use the Metadata API to upload a shapefile and display it as a custom map layer in Oracle Field Service. A shapefile is a vector data storage format for storing geographic information such as location, shape, and attributes of geographic features. For more information about shapefiles, see About Shapefiles.

You can use custom map layers even without hosting the map layer data on Oracle Field Service. You can use the Map Layers resource in the Metadata API to create, modify, and delete internal and external map layers.

Let's look at an example to understand the use of custom map layers.

Vision Corporation is a company, which installs network infrastructure and network components. They use custom map layers to overlay network infrastructure like cables, pipes, fiber, and network components like nodes, transformers, cabinets, amplifiers on a map. The field technicians troubleshooting signal related issues in a neighborhood use this map to identify the location of the upstream amplifier to resolve the issue. They can easily identify the upstream amplifier location, by opening the map, selecting the amplifier map layer, and checking for the amplifier location.

This use case discusses how you can:

Create a Custom Map Layer

You can create a custom map layer using the 'Create a custom map layer' operation as follows:

Construct the request URL for the 'Create a custom map layer' operation.
Construct the request body with the object properties of the custom map layer you want to create.
Run the request using the POST HTTP method to create the custom map layer.

Example URL

Here's the complete URL with the POST HTTP method.

POST  
https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscMetadata/v1/mapLayers

Example Request

Here's an example of the request body in JSON format.

{
  "label": "somelb1",           
  "type": "external",           
  "status": "active",           
  "sourceName": "someSourceName",   
  "theme": "someTheme",         
  "url": "https://hello.com",    
  "translations": [             
    {
      "language": "en",
      "name": "Some Name"
    },
    {
      "language": "es",
      "name": "Un Nombre"
    }
  ]
}

Example Response

Here's an example of the response body in JSON format.

{
    "label": "somelb1",         
    "type": "external",         
    "status": "active",         
    "sourceName": "someSourceName", 
    "theme": "someTheme",       
    "url": "https://hello.com",  
    "text": "Some Name",        
    "links": [
        {
            "rel": "canonical",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscMetadata/v1/mapLayers/somelb1"
        },
        {
            "rel": "describedby",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscMetadata/v1/metadata-catalog/mapLayers"
        }
    ]
}

Upload a Shapefile as a Custom Map Layer

Before you upload a shapefile, complete these tasks:

Create a shapefile (zip archive) and ensure that it's accessible over HTTPS protocol over a public network.
Obtain the Spatial Reference System Identifier (SRID) of the shapefile you created.

Note:
SRID is used to identify projected, unprojected, and local spatial coordinate system definitions. When you upload a shapefile using the Metadata API, the request must contain the same SRID as the shapefile.
Ensure that you have read-write access to Metadata API, and then to Map Layers. For more information on authorizing access to APIs, see Authenticate and Authorize

You can upload a shapefile as a custom map layer by using the 'Populate a custom map layer' operation as follows:

Construct the request URL for the 'Populate a custom map layer' operation.
Construct the request body with the object properties of the custom map layer you want to populate.
Run the request using the POST HTTP method to upload the shapefile and populate it as a custom map layer.
The upload process downloads, unpacks, and imports the shapefile to Oracle Field Service.

Example URL

Here's the complete URL with the POST HTTP method.

POST /rest/ofscMetadata/v1/mapLayers/custom-actions/populateLayers/

Example Request

Here's an example of the request body in JSON format.


{
    "URL": "https://www.example.com/workzones/shapes/sip/fileData.zip",
    "authentication" : 
    {
        "type" : "basic",       
        "username": "TIGER",    
        "password": "psw"       
    },
    "layerLabel": "AIRPORTS",   
    "SRID": 4269,               
    "shapeTitleColumn": "IATA", 
    "shapeHintColumns": 
  [       
      {
        "sourceColumn": "NAME", 
        "defaultName":  "Name"  
      },
      {
        "sourceColumn": "ICAO",
        "defaultName":  "ICAO Code"
      },
      {
        "sourceColumn": "COUNTRY",
        "defaultName":  "Country"
      },
      {
        "sourceColumn": "CITY",
        "defaultName":  "City"
      },
      {
        "sourceColumn": "ALTITUDE",
        "defaultName":  "Altitude (ft)"
      },
      {
        "sourceColumn": "TZNAME",
        "defaultName":  "Time Zone"
      }
  ]
}

Example Response

Here's an example of the response body in JSON format.


{
		"status": "pending",
		"time": "2016-12-27 16:57:38",
		"downloadId": "3cc850bf2ec78e2a4c1e01d3b8e43fbd",
		"links": [
		{
			"rel": "canonical",
			"href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscMetadata/v1/mapLayers/custom-actions/populateLayers/3cc850bf2ec78e2a4c1e01d3b8e43fbd"
		},
		{
			"rel": "describedby",
			"href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscMetadata/v1/metadata-catalog/mapLayers"
}
]
}

Check Custom Map Layer Population Status

You can check the status of the upload process by using the 'Check custom map layer population status' operation as follows:

Construct the request URL for the 'Check custom map layer population status' operation.
Specify the path parameter downloadId as 5a93c598f92621321d4fd257bf0da6d6 in the operation URL.
Run the request using the GET HTTP method to retrieve the import status of the custom map layer.

Example URL

Here's the complete URL with the GET HTTP method.

GET /rest/ofscMetadata/v1/workZones/custom-actions/populateShapes/5a93c598f92621321d4fd257bf0da6d6

Example Response Body

Here's an example of the response body in JSON format.


{
    "downloadID":5a93c598f92621321d4fd257bf0da6d6,  
    "status":"pending"                           
}

Constraints

Here are a few things to keep in mind while configuring custom map layers:

Make sure that the size of the shapefile (zip archive) doesn't exceed 2 GB, to avoid excessive network traffic consumption and file system usage.
Although the maximum size of the shapefile is 2 GB, you can store only upto 1 GB of data in Oracle Field Service as internal custom map layers. The shapefile might contain additional information that isn't imported.
You can configure only upto 10 internal custom map layers for one Oracle Field Service instance using the POST request /mapLayers/custom-actions/populateLayers in Metadata API. However, you can create any number of layers using the Oracle Field Service user interface.
You can't use internal custom map layers in the offline mode.

Recommendations and Best Practices

It's a good idea to consider these best practices while configuring custom map layers:

Make sure that the name of a custom map layer doesn't exceed 10 characters. In Oracle Field Service Mobile for Android and iOS, the name of the custom map layer is truncated if it's too long to fit in the user interface control.
When you upload a shapefile archive, files must be at a root level in the archive. All the files that are located in subdirectories are ignored.
Upload the archive with only one shapefile at a time.
Use a Geographic Information System (GIS) mapping tool, such as QGIS, Esri, to create and update a shapefile.