Jump to

• Request
• Response
• Examples

Populate a custom map layer

post

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

This operation creates a shapefile and converts it into a map layer in Oracle Field Service. This operation is asynchronous.

Only 10 internal custom map layers are allowed for an Oracle Field Service environment. Therefore only 10 different labels are allowed in a request to create a map layer.

A shapefile (zip archive) is limited to 2 GB. Not all the information in the zip archive is imported and therefore the maximum amount of data stored as Internal Custom Map Layers is limited to 1 GB per Oracle Field Service environment. Oracle Field Service downloads the shapefile from the specified url in the background. You should verify the status of shapefile download and creation using the 'Check custom map layer population status' api.

Request

Body ()

The request body object used for populating a custom map layer.

Root Schema : Populate Layers Request

Type: object

Title: Populate Layers Request

The schema of the request body object for this operation.

Show Source

• authentication(required): object Authentication
  Title: Authentication

  The authentication used for downloading the geo-data from the external source specified in the URL field.

  • If the URL points to an HTTP service, and the type of the authentication specified is 'basic', then Oracle Field Service sends a request to this URL to authenticate using the HTTP-Basic scheme with the username and password as credentials.
  • If the URL points to an FTP service, and the type of the authentication specified is 'ftp', then Oracle Field Service connects via the FTP protocol using the username and password as credentials.
  • If the type of the authentication specified is 'none', then Oracle Field Service downloads the geo-data without any authentication.
• layerLabel(required): string
  Title: Layer Label

  Minimum Length: 1

  Maximum Length: 24

  Pattern: ^[A-Za-z0-9_]+$

  The unique identifier of the layer.
• shapeHintButton: object Plugin or form map layer hint button
  Title: Plugin or form map layer hint button

  The object representing selected Custom Form or Plugin will be displayed as a button on layer hint. Parameters specified in Plugin/Form Field will be sent to the selected Custom Form or Plugin.
• shapeHintColumns: array Shape Hint Columns
  Title: Shape Hint Columns

  The set of objects that define the contents of the hint for the shapes on the map.
• shapeTitleColumn: string
  Title: Shape Title Column

  Minimum Length: 1

  Maximum Length: 255

  The name of the non-spatial column that contains the titles of the shapes that are displayed on the map.
• SRID(required): integer
  Title: SRID

  The spatial reference identifier (SRID) of the geo-data in the shape file.
• URL(required): string
  Title: URL

  Minimum Length: 1

  Maximum Length: 255

  The URL of the external source from which the geo-data is downloaded. Supported protocols: HTTPS only.

{
    "title":"Populate Layers Request",
    "type":"object",
    "description":"The schema of the request body object for this operation.",
    "properties":{
        "URL":{
            "title":"URL",
            "description":"The URL of the external source from which the geo-data is downloaded. Supported protocols: HTTPS only.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        },
        "authentication":{
            "title":"Authentication",
            "description":"<p>The authentication used for downloading the geo-data from the external source specified in the URL field.</p><ul><li>If the URL points to an HTTP service, and the type of the authentication specified is 'basic', then Oracle Field Service sends a request to this URL to authenticate using the HTTP-Basic scheme with the username and password as credentials.</li><li>If the URL points to an FTP service, and the type of the authentication specified is 'ftp', then Oracle Field Service connects via the FTP protocol using the username and password as credentials.</li><li>If the type of the authentication specified is 'none', then Oracle Field Service downloads the geo-data without any authentication.</li>",
            "type":"object",
            "properties":{
                "type":{
                    "title":"Type",
                    "description":"The type of the authentication. The allowed values are 'none', 'basic', and 'ftp'. ",
                    "type":"string",
                    "enum":[
                        "basic",
                        "ftp",
                        "none"
                    ]
                },
                "username":{
                    "title":"Username",
                    "description":"The username used to authenticate the connection between Oracle Field Service and the external source.",
                    "type":"string"
                },
                "password":{
                    "title":"Password",
                    "description":"The password used to authenticate the connection between Oracle Field Service and the external source.",
                    "type":"string"
                }
            },
            "required":[
                "type"
            ]
        },
        "shapeTitleColumn":{
            "title":"Shape Title Column",
            "description":"The name of the non-spatial column that contains the titles of the shapes that are displayed on the map.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        },
        "shapeHintColumns":{
            "title":"Shape Hint Columns",
            "description":"The set of objects that define the contents of the hint for the shapes on the map.",
            "type":"array",
            "items":{
                "type":"object",
                "properties":{
                    "sourceColumn":{
                        "title":"Source Column Name",
                        "description":"The unique name of the source column in the user's language. The name specified in this parameter is displayed as a hint.",
                        "type":"string"
                    },
                    "defaultName":{
                        "title":"Default Column Name",
                        "description":"The unique name of the shapefile column.",
                        "type":"string"
                    },
                    "pluginFormField":{
                        "type":"string",
                        "title":"Plugin or Form Column Name",
                        "maxLength":255
                    }
                },
                "required":[
                    "sourceColumn",
                    "defaultName",
                    "pluginFormField"
                ]
            }
        },
        "shapeHintButton":{
            "type":"object",
            "title":"Plugin or form map layer hint button",
            "description":"The object representing selected Custom Form or Plugin will be displayed as a button on layer hint. Parameters specified in Plugin/Form Field will be sent to the selected Custom Form or Plugin.",
            "properties":{
                "actionType":{
                    "type":"string",
                    "enum":[
                        "plugin",
                        "form"
                    ],
                    "title":"PluginForm Type",
                    "description":"The type of plugin or form the activity hint button on map layer."
                },
                "label":{
                    "type":"string",
                    "minLength":1,
                    "maxLength":64,
                    "title":"Label for plugin or form",
                    "description":"The label plugin or form for map layer hint."
                }
            },
            "required":[
                "actionType",
                "label"
            ]
        },
        "layerLabel":{
            "title":"Layer Label",
            "description":"The unique identifier of the layer.",
            "type":"string",
            "minLength":1,
            "maxLength":24,
            "pattern":"^[A-Za-z0-9_]+$"
        },
        "SRID":{
            "title":"SRID",
            "description":"The spatial reference identifier (SRID) of the geo-data in the shape file.",
            "type":"integer"
        }
    },
    "required":[
        "URL",
        "authentication",
        "layerLabel",
        "SRID"
    ]
}

Nested Schema : Authentication

Type: object

Title: Authentication

The authentication used for downloading the geo-data from the external source specified in the URL field.

• If the URL points to an HTTP service, and the type of the authentication specified is 'basic', then Oracle Field Service sends a request to this URL to authenticate using the HTTP-Basic scheme with the username and password as credentials.
• If the URL points to an FTP service, and the type of the authentication specified is 'ftp', then Oracle Field Service connects via the FTP protocol using the username and password as credentials.
• If the type of the authentication specified is 'none', then Oracle Field Service downloads the geo-data without any authentication.

Show Source

• password: string
  Title: Password

  The password used to authenticate the connection between Oracle Field Service and the external source.
• type(required): string
  Title: Type

  Allowed Values: [ "basic", "ftp", "none" ]

  The type of the authentication. The allowed values are 'none', 'basic', and 'ftp'.
• username: string
  Title: Username

  The username used to authenticate the connection between Oracle Field Service and the external source.

{
    "title":"Authentication",
    "description":"<p>The authentication used for downloading the geo-data from the external source specified in the URL field.</p><ul><li>If the URL points to an HTTP service, and the type of the authentication specified is 'basic', then Oracle Field Service sends a request to this URL to authenticate using the HTTP-Basic scheme with the username and password as credentials.</li><li>If the URL points to an FTP service, and the type of the authentication specified is 'ftp', then Oracle Field Service connects via the FTP protocol using the username and password as credentials.</li><li>If the type of the authentication specified is 'none', then Oracle Field Service downloads the geo-data without any authentication.</li>",
    "type":"object",
    "properties":{
        "type":{
            "title":"Type",
            "description":"The type of the authentication. The allowed values are 'none', 'basic', and 'ftp'. ",
            "type":"string",
            "enum":[
                "basic",
                "ftp",
                "none"
            ]
        },
        "username":{
            "title":"Username",
            "description":"The username used to authenticate the connection between Oracle Field Service and the external source.",
            "type":"string"
        },
        "password":{
            "title":"Password",
            "description":"The password used to authenticate the connection between Oracle Field Service and the external source.",
            "type":"string"
        }
    },
    "required":[
        "type"
    ]
}

Nested Schema : Plugin or form map layer hint button

Type: object

Title: Plugin or form map layer hint button

The object representing selected Custom Form or Plugin will be displayed as a button on layer hint. Parameters specified in Plugin/Form Field will be sent to the selected Custom Form or Plugin.

Show Source

• actionType(required): string
  Title: PluginForm Type

  Allowed Values: [ "plugin", "form" ]

  The type of plugin or form the activity hint button on map layer.
• label(required): string
  Title: Label for plugin or form

  Minimum Length: 1

  Maximum Length: 64

  The label plugin or form for map layer hint.

{
    "type":"object",
    "title":"Plugin or form map layer hint button",
    "description":"The object representing selected Custom Form or Plugin will be displayed as a button on layer hint. Parameters specified in Plugin/Form Field will be sent to the selected Custom Form or Plugin.",
    "properties":{
        "actionType":{
            "type":"string",
            "enum":[
                "plugin",
                "form"
            ],
            "title":"PluginForm Type",
            "description":"The type of plugin or form the activity hint button on map layer."
        },
        "label":{
            "type":"string",
            "minLength":1,
            "maxLength":64,
            "title":"Label for plugin or form",
            "description":"The label plugin or form for map layer hint."
        }
    },
    "required":[
        "actionType",
        "label"
    ]
}

Nested Schema : Shape Hint Columns

Type: array

Title: Shape Hint Columns

The set of objects that define the contents of the hint for the shapes on the map.

Show Source

• Array of: object items

{
    "title":"Shape Hint Columns",
    "description":"The set of objects that define the contents of the hint for the shapes on the map.",
    "type":"array",
    "items":{
        "type":"object",
        "properties":{
            "sourceColumn":{
                "title":"Source Column Name",
                "description":"The unique name of the source column in the user's language. The name specified in this parameter is displayed as a hint.",
                "type":"string"
            },
            "defaultName":{
                "title":"Default Column Name",
                "description":"The unique name of the shapefile column.",
                "type":"string"
            },
            "pluginFormField":{
                "type":"string",
                "title":"Plugin or Form Column Name",
                "maxLength":255
            }
        },
        "required":[
            "sourceColumn",
            "defaultName",
            "pluginFormField"
        ]
    }
}

Nested Schema : items

Type: object

Show Source

• defaultName(required): string
  Title: Default Column Name

  The unique name of the shapefile column.
• pluginFormField(required): string
  Title: Plugin or Form Column Name

  Maximum Length: 255
• sourceColumn(required): string
  Title: Source Column Name

  The unique name of the source column in the user's language. The name specified in this parameter is displayed as a hint.

{
    "type":"object",
    "properties":{
        "sourceColumn":{
            "title":"Source Column Name",
            "description":"The unique name of the source column in the user's language. The name specified in this parameter is displayed as a hint.",
            "type":"string"
        },
        "defaultName":{
            "title":"Default Column Name",
            "description":"The unique name of the shapefile column.",
            "type":"string"
        },
        "pluginFormField":{
            "type":"string",
            "title":"Plugin or Form Column Name",
            "maxLength":255
        }
    },
    "required":[
        "sourceColumn",
        "defaultName",
        "pluginFormField"
    ]
}

Back to Top

Response

Supported Media Types

• application/schema+json
• application/json

200 Response

This section describes the 200 status response for this operation.

Body ()

Root Schema : Populate Layers Response

Type: object

Title: Populate Layers Response

The schema of the response body object for this operation.

Show Source

• downloadId: integer
  Title: Download ID

  The identifier of the shape file specified in the request.
• status: string
  Title: Status

  The status of the downloaded shape file.
• time: string
  Title: Time

  The time when the operation started.

{
    "title":"Populate Layers Response",
    "description":"The schema of the response body object for this operation.",
    "properties":{
        "status":{
            "title":"Status",
            "description":"The status of the downloaded shape file.",
            "type":"string"
        },
        "time":{
            "title":"Time",
            "description":"The time when the operation started.",
            "type":"string"
        },
        "downloadId":{
            "title":"Download ID",
            "description":"The identifier of the shape file specified in the request.",
            "type":"integer"
        }
    }
}

Default Response

This section describes the default error response for this operation.

Body ()

Root Schema : Error

Type: object

Show Source

• detail: string
  The detailed description of this error.
• status: string
  The HTTP status code of this error.
• title(required): string
  The brief description of this error.
• type(required): string
  The URL of the web page containing more details about this error.

{
    "properties":{
        "type":{
            "type":"string",
            "description":"The URL of the web page containing more details about this error."
        },
        "title":{
            "type":"string",
            "description":"The brief description of this error."
        },
        "status":{
            "type":"string",
            "description":"The HTTP status code of this error."
        },
        "detail":{
            "type":"string",
            "description":"The detailed description of this error."
        }
    },
    "required":[
        "type",
        "title"
    ]
}

Back to Top

Examples

The following example shows how to create a shapefile and convert it into a map layer in Oracle Field Service Cloud by submitting a POST request on the REST resource using cURL.

Example of Request Header

The following shows an example of the request header.

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

Example of Request Body

The following example shows the contents of the request body in JSON format.

{
    "URL": "https://www.example.com/workzones/shapes/sip/fileData.zip",
    "authentication" : 
    {
        "type" : "basic",       
        "username": "<CLIENT-ID>@<INSTANCE-NAME>",    
        "password": "<CLIENT-SECRET>"       
    },
    "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 of Response Header

The following shows an example of the response header.

HTTP/1.1 200 OK

Example of Response Body

The following example shows the contents of the response body in JSON format.

{
    "downloadID":5a93c598f92621321d4fd257bf0da6d6,  
    "status":"pending",                             
    "time": "2016-01-05 12:58:54"                   
}

Back to Top