Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: ChooseBestFacilities

require(["esri/dijit/analysis/ChooseBestFacilities"], function(ChooseBestFacilities) { /* code goes here */ });

Description

(Added at v3.16)
Choose Best Facilities allows you to choose the best locations for facilities. The tool allocates locations with demand for the facilities, in a way that satisfies the specified goal. The widget provides various options to solve specific problems. These options include:
  • Allocating to existing facilities
  • Minimizing travel time
  • Maximizing coverage
  • Maximizing coverage with capacity
  • Covering a percentage of demand
Facilities represent locations that offer some kind of service such as fire stations, schools, libraries, stores, or distribution centers. Demand locations represent locations that have demand for the services offered by the facilities, such as census block points that summarize the population in a given area. For a more detailed description of how this widget works, please see the ArcGIS Online help documentation.

Samples

Search for samples that use this class.

Class hierarchy

esri/dijit/analysis/AnalysisBase
|_esri/dijit/analysis/ChooseBestFacilities

Constructors

NameSummary
new ChooseBestFacilities(params, srcNodeRef)Creates a new ChooseBestFacilities dijit using the given DOM node.

Properties

NameTypeSummary
analysisGpServerStringThe URL to the analysis service, for example "http://analysis.arcgis.com/arcgis/rest/services/tasks/GPServer".
candidateCountNumberThe number of facilities to choose when allocating demand locations.
candidateFacilitiesCapacityStringThis specifies how much demand every facility in the candidateFacilitiesLayer is capable of supplying.
candidateFacilitiesCapacityFieldStringString value indicating the field name on the candidateFacilitiesLayer representing how much demand each facility in the candidatesFacilitiesLayer is capable of supplying.
candidateFacilitiesLayerFeatureLayerA point layer specifying one or more locations that act as facilities by providing some kind of service.
demandNumberThe amount of demand available at every demand locations.
demandFieldStringString value indicating the field name on the demandLocationLayer representing the amount of demand available at each demand location.
demandLocationLayerFeatureLayerA point layer specifying the locations that have demand for facilities.
demandLocationLayersFeatureLayer[]Array of point layers to be used for choosing the demandLocationLayer.
enableTravelModesBooleanWhen true, Travel Modes (Driving Time) is enabled for the inputLayer with the point geometries (esriGeometryPoint).
featureLayersFeatureLayer[]Array of point layers used for setting the required facilities layer and candidate facilities layer.
folderIdStringSets the selected folder of the select folder dropdown.
folderNameStringSets the selected folder of the select folder dropdown.
mapMapReference to the map.
maxTravelRangeNumberThe maximum travel time or distance allowed between a demand location and its allocated facility.
maxTravelRangeFieldStringString value indicating the field name on the demandLocationLayer specifying the maximum travel time or distance allowed between a demand location and its allocated facility.
outputLayerNameStringThe name of the output layer to be displayed in the result layer nameinputbox.
percentDemandCoverageNumberThe percentage of the total demand that you want the chosen and required facilities to capture.
portalSelfObjectThe self response of the Portal.
portalUrlStringThe URL to the ArcGIS organization or Portal site where the GP server is hosted.
requiredFacilitiesCapacityNumberSpecify how much demand every facility in the requiredFacilitiesLayer is capable of supplying.
requiredFacilitiesCapacityFieldStringA field on the requiredFacilitiesLayer representing how much demand each facility in this layer is capable of supplying.
requiredFacilitiesLayerFeatureLayerA point layer specifying one or more locations that act as facilities by providing some kind of service.
returnFeatureCollectionBooleanIndicates whether to return the result of analysis as a client-side feature collection.
showChooseExtentBooleanIndicates whether the "choose extent checkbox" is displayed.
showCreditsBooleanIndicates whether to show the credit options.
showHelpBooleanIndicates whether the help links are displayed.
showReadyToUseLayersBooleanIndicates whether to add an option to the UI that allows users to choose ready-to-use analysis layers from the Living Atlas Analysis Layers.
showSelectAnalysisLayerBooleanIndicates whether to display a dropdown menu listing valid input analysis layers.
showSelectFolderBooleanIndicates whether the select folder dropdown will be displayed.
titleStringThe default widget title with a custom title.

Methods

NameReturn typeSummary
cancel(jobInfo)NoneCancels an analysis job that is being processed.
checkJobStatus(jobId)NoneStarts checking the analysis job status for the given jobId.
execute(params)NoneStarts an analysis tool.
getCreditsEstimate(toolName, jobParams)DeferredGets credits estimate for a specific analysis job.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
closeFires when close icon is clicked or when run analysis button is clicked.
drawtool-activateFires when the drawn boundaries option is activated.
drawtool-deactivateFires when the drawn boundaries option is deactivated.
job-cancel
{
  response: <Object>
}
Fires when the job in cancelled.
job-fail
{
  error: <Object>
}
Fires when the job fails.
job-result
{
  result: <Object>
}
Fires after the job fetches result data.
job-status
{
  jobInfo: <Object>
}
Fires when the job execution status is received.
job-submit
{
  params: <Object>
}
Fires when the job is submitted to the server for asynchronous processing.
job-success
{
  jobInfo: <Object>
}
Fires when the job succeeds.
start
{
  params: <Object>
}
Fires when the execute method is called.
Constructor Details

new ChooseBestFacilities(params, srcNodeRef)

Creates a new ChooseBestFacilities dijit using the given DOM node.
Parameters:
<Object> params Required Various options to configure this dijit. All the properties can be passed into the params object.
<Node | String> srcNodeRef Required Reference or id of a HTML element that this dijit is rendered into.
params properties:
<String> analysisGpServer Optional The URL to the analysis service, for example "http://analysis.arcgis.com/arcgis/rest/services/tasks/GPServer".
<Number> candidateCount Optional The number of facilities to choose when allocating demand locations. If requiredFacilitiesLayer is specified, the number of facilities to choose should be equal to or greater than the count of locations in the requiredFacilitiesLayer. Default value is 1.
<String> candidateFacilitiesCapacity Optional Specify how much demand every facility in the candidateFacilitiesLayer is capable of supplying. Default value is "unlimited".
<String> candidateFacilitiesCapacityField Optional String value indicating the field name on the candidateFacilitiesLayer representing how much demand each facility in the candidatesFacilitiesLayer is capable of supplying. This parameter takes precedence when the candidateFacilitiesCapacity parameter is also specified.
<FeatureLayer> candidateFacilitiesLayer Optional A point layer specifying one or more locations that act as facilities by providing some kind of service. Facilities specified by this parameter are not required to be part of the output solution and will be used only after all the facilities from the candidatesFacilitiesLayer have been used when allocating demand locations.
<Number> demand Optional The amount of demand available at every demand locations. Default value is 1.
<String> demandField Optional String value indicating the field name on the demandLocationLayer representing the amount of demand available at each demand location. Only numeric field types are allowed.
<FeatureLayer> demandLocationLayer Optional A point layer specifying the locations that have demand for facilities. If this is not passed in, it's set to the first layer in the demandLocationLayers list.
<FeatureLayer[]> demandLocationLayers Required Array of point layers to be used for choosing the demandLocationLayer.
<Boolean> enableTravelModes Optional When true, Travel Modes (Driving Time) is enabled for the inputLayer with the point geometries (esriGeometryPoint). Default value is true.
<FeatureLayer[]> featureLayers Required Array of point layers used for setting the required facilities layer and candidate facilities layer.
<String> folderId Optional Sets the selected folder of the select folder dropdown. This is based on the provided folderId, when showSelectFolder is true.
<String> folderName Optional Sets the selected folder of the select folder dropdown. This is based on the provided folderName when showSelectFolder is true.
<Map> map Optional Reference to the map.
<Number> maxTravelRange Optional The maximum travel time or distance allowed between a demand location and its allocated facility. Default value is 1 .
<String> maxTravelRangeField Optional String value indicating the field name on the demandLocationLayer specifying the maximum travel time or distance allowed between a demand location and its allocated facility. This parameter takes precedence when the maxTravelRange property is also specified.
<String> outputLayerName Optional The name of the output layer to be displayed in the result layer nameinputbox.
<Number> percentDemandCoverage Optional The percentage of the total demand that you want the chosen and required facilities to capture. Default value is 100.
<String> portalUrl Optional The URL to the ArcGIS organization or Portal site where the GP server is hosted. For example, "http://www.arcgis.com".
<Number> requiredFacilitiesCapacity Optional Specify how much demand every facility in the requiredFacilitiesLayer is capable of supplying.
<String> requiredFacilitiesCapacityField Optional A field on the requiredFacilitiesLayer representing how much demand each facility in this layer is capable of supplying. This parameter takes precedence when requiredFacilitiesCapacityparameter is also specified. Default is "unlimited".
<FeatureLayer> requiredFacilitiesLayer Optional A point layer specifying one or more locations that act as facilities by providing some kind of service. Facilities specified by this parameter are required to be part of the output solution and will be used before any facilities from the candidatesFacilitiesLayer when allocating demand locations.
<Boolean> returnFeatureCollection Optional Indicates whether to return the result of analysis as a client-side feature collection.
<Boolean> showChooseExtent Optional Indicates whether the "choose extent checkbox" is displayed.
<Boolean> showCredits Optional Indicates whether to show the credit options.
<Boolean> showHelp Optional Indicates whether the help links are displayed.
<Boolean> showReadyToUseLayers Optional Indicates whether to add an option to the UI that allows users to choose ready-to-use analysis layers from the Living Atlas Analysis Layers.
<Boolean> showSelectAnalysisLayer Optional Indicates whether to display a dropdown menu listing valid input analysis layers.
<Boolean> showSelectFolder Optional Indicates whether the select folder dropdown will be displayed.
<String> title Optional The default widget title with a custom title.
Sample:
var toolParams = {
  demandLocationLayers: [lots,  potentialparks, developerlots],
  featureLayers: [lots, potentialparks, developerlots],
  portalUrl: "http://www.arcgis.com",  
  map: map,
  returnFeatureCollection: false
  };

var chooseBestTool = new ChooseBestFacilities(toolParams, "toolDiv"); 
chooseBestTool.startup();
Property Details

<String> analysisGpServer

The URL to the analysis service, for example "http://analysis.arcgis.com/arcgis/rest/services/tasks/GPServer". Required when portalUrl is not specified.

<Number> candidateCount

The number of facilities to choose when allocating demand locations. If requiredFacilitiesLayer is specified, the number of facilities to choose should be equal to or greater than the count of locations in the requiredFacilitiesLayer.
Default value: 1

<String> candidateFacilitiesCapacity

This specifies how much demand every facility in the candidateFacilitiesLayer is capable of supplying.
Default value: "unlimited"

<String> candidateFacilitiesCapacityField

String value indicating the field name on the candidateFacilitiesLayer representing how much demand each facility in the candidatesFacilitiesLayer is capable of supplying. This parameter takes precedence when the candidateFacilitiesCapacity parameter is also specified.

<FeatureLayer> candidateFacilitiesLayer

A point layer specifying one or more locations that act as facilities by providing some kind of service. Facilities specified by this parameter are not required to be part of the output solution and will be used only after all the facilities from the candidatesFacilitiesLayer have been used when allocating demand locations.
Default value: 1

<Number> demand

The amount of demand available at every demand locations.
Default value: 1

<String> demandField

String value indicating the field name on the demandLocationLayer representing the amount of demand available at each demand location. Only numeric field types are allowed.

<FeatureLayer> demandLocationLayer

A point layer specifying the locations that have demand for facilities. If this is not passed in, it's set to the first layer in the demandLocationLayers list.

<FeatureLayer[]> demandLocationLayers

Array of point layers to be used for choosing the demandLocationLayer.

<Boolean> enableTravelModes

When true, Travel Modes (Driving Time) is enabled for the inputLayer with the point geometries (esriGeometryPoint).
Default value: true

<FeatureLayer[]> featureLayers

Array of point layers used for setting the required facilities layer and candidate facilities layer.

<String> folderId

Sets the selected folder of the select folder dropdown. This is based on the provided folderId, when showSelectFolder is true.

<String> folderName

Sets the selected folder of the select folder dropdown. This is based on the provided folderName when showSelectFolder is true.

<Map> map

Reference to the map. Required when showChooseExtent is true.
Default value: null

<Number> maxTravelRange

The maximum travel time or distance allowed between a demand location and its allocated facility.
Default value: 1

<String> maxTravelRangeField

String value indicating the field name on the demandLocationLayer specifying the maximum travel time or distance allowed between a demand location and its allocated facility. This parameter takes precedence when the maxTravelRange property is also specified.

<String> outputLayerName

The name of the output layer to be displayed in the result layer nameinputbox.

<Number> percentDemandCoverage

The percentage of the total demand that you want the chosen and required facilities to capture.
Default value: 100

<Object> portalSelf

The self response of the Portal. When set, optimizes performance to reuse self calls made by the widget. For more documentation on the properties of this object, see the Portal Self ArcGIS REST API documentation. (Added at v3.14)

<String> portalUrl

The URL to the ArcGIS organization or Portal site where the GP server is hosted. For example, "http://www.arcgis.com".

<Number> requiredFacilitiesCapacity

Specify how much demand every facility in the requiredFacilitiesLayer is capable of supplying.

<String> requiredFacilitiesCapacityField

A field on the requiredFacilitiesLayer representing how much demand each facility in this layer is capable of supplying. This parameter takes precedence when requiredFacilitiesCapacityparameter is also specified. Default is "unlimited".
Default value: "unlimited"

<FeatureLayer> requiredFacilitiesLayer

A point layer specifying one or more locations that act as facilities by providing some kind of service. Facilities specified by this parameter are required to be part of the output solution and will be used before any facilities from the candidatesFacilitiesLayer when allocating demand locations.

<Boolean> returnFeatureCollection

Indicates whether to return the result of analysis as a client-side feature collection.
Default value: false

<Boolean> showChooseExtent

Indicates whether the "choose extent checkbox" is displayed.
Default value: true

<Boolean> showCredits

Indicates whether to show the credit options.
Default value: true

<Boolean> showHelp

Indicates whether the help links are displayed.
Default value: true

<Boolean> showReadyToUseLayers

Indicates whether to add an option to the UI that allows users to choose ready-to-use analysis layers from the Living Atlas Analysis Layers.
Default value: true

<Boolean> showSelectAnalysisLayer

Indicates whether to display a dropdown menu listing valid input analysis layers.
Default value: true

<Boolean> showSelectFolder

Indicates whether the select folder dropdown will be displayed.
Default value: false

<String> title

The default widget title with a custom title.
Method Details

cancel(jobInfo)

Cancels an analysis job that is being processed.
Parameters:
<Object> jobInfo Required An object containing job information including job ID, status, message, etc returned by the job-status event.

checkJobStatus(jobId)

Starts checking the analysis job status for the given jobId. (Added at v3.12)
Parameters:
<String> jobId Required Job id of the analysis job to check.

execute(params)

Starts an analysis tool.
Parameters:
<String> params Required See the object specifications table below for the structure of the params object.
Object Specifications:
<params>
<Object> itemParams Optional Parameters for creating the output service item. Refer to the ArcGIS REST API - Add Item help topic for a list of available parameters. Only used when the analysis task creates a hosted service.
<Object> jobParams Required The input job parameters. Required parameters vary from class to class. Refer to the Analysis REST API Documentation for details (Under the Request Parameters section of each task). When creating a hosted service, a layer name is required.
Sample:
var params = {
  itemParams: {
    description: "Item description.",
    snippet: "A short summary about this item.",
    tags: "<tag1>, <tag2>, <tag3>, ... ",
    typeKeywords: "<typeKeyword1>, <typeKeyword2>, <typeKeyword3>, ... "
  },
  jobParams: {
    outputLayerName: "{\"serviceProperties\":{\"name\":\"Name of the output feature service\"},\"itemProperties\":{\"itemId\":\"<itemId>\"}}",
    ...
  }
}

analysisBase.execute(params);

getCreditsEstimate(toolName, jobParams)

Gets credits estimate for a specific analysis job. This method returns a deferred object. The callback function has an object containing the number of records to be processed and the estimated credit cost for this job.
Return type: Deferred
Parameters:
<String> toolName Required The name of the analysis tool from which a credits estimate will be returned.
<String> jobParams Required The input job parameters. This value should be the same as the jobParams property of an analysis tool dijit. Refer to the jobParams property of this class for detailed syntax.
Sample:
analysisBase.getCreditsEstimate("FindHotSpots",{
  AnalysisLayer: layer._json,
  context: '{"outSR":{"wkid":102100}}',
  isProcessInfo: true,
  returnFeatureCollection: true
}).then(function(result){
  console.log(result);
});

//the "result" argument above:
//{
//  "cost": 1.472,
//  "totalRecords": 1472,
//}
Event Details
[ On Style Events | Connect Style Event ]

close

Fires when close icon is clicked or when run analysis button is clicked. (Added at v3.7)

drawtool-activate

Fires when the drawn boundaries option is activated. Only valid when using the FindHotSpots or ExtractData widget. A typical usage is to disable the zoom/pan/popup handlers when drawing is activated. (Added at v3.7)

drawtool-deactivate

Fires when the drawn boundaries option is deactivated. Only valid when using the FindHotSpots or ExtractData widget. A typical usage is to enable the zoom/pan/popup handlers when drawing is deactivated. (Added at v3.7)

job-cancel

Fires when the job in cancelled. (Added at v3.7)
Event Object Properties:
<Object> response An GP job object returned by the GP server. Refer to the GP Job and the Checking job status topics in the ArcGIS REST API Documentation for more information and syntax.
{
  "inputs": {},
  "jobId": <job id>,
  "jobStatus": <job status>,
  "messages": <an array of message text>,
  "results": {}
}

job-fail

Fires when the job fails. (Added at v3.7)
Event Object Properties:
<Object> error The error message returned by a failed job.
{
  "analysisReport": <analysis report message>,
  "dataType": <analysis report message>,
  "paramName": < parameter  name >,
  "value": <output item info | feature collection>
}

job-result

Fires after the job fetches result data. The returned argument contains the output value (either a feature collection or a url to the hosted service), which you may add to the map as a feature layer. (Added at v3.7)
Event Object Properties:
<Object> result An object containing the resulted message and value. Based on the GP result object returned by the GP server with the analysisReport property added.

If output is a feature collection, value is a feature collection object; if output is a hosted arcgis.com feature service, value is an object with item information including ID and URL. Refer to the ArcGIS REST API documentation - Feature Output for more information.
{
  "analysisReport": <analysis report message>,
  "dataType": <analysis report message>,
  "paramName": < parameter  name >,
  "value": <output item info | feature collection>
}
Sample:
analysisTool.on("job-result", function(result){
  var featureLayer = new FeatureLayer(result.value['url'] || result.value);
  map.addLayer(featureLayer);
})

job-status

Fires when the job execution status is received. (Added at v3.7)
Event Object Properties:
<Object> jobInfo An object containing job information including job ID, status, message, etc. Based on the GP job object returned by the GP server with the jobParam property attached. Refer to the GP Job and the Checking job status topics in the ArcGIS REST API Documentation for more information and syntax.
{
  "inputs": {},
  "jobParams": <job parameters>,
  "jobId": <job id>,
  "jobStatus": <job status>,
  "messages": <an array of message text>,
  "results": {}
}

job-submit

Fires when the job is submitted to the server for asynchronous processing. (Added at v3.7)
Event Object Properties:
<Object> params The input job parameters.

job-success

Fires when the job succeeds. (Added at v3.7)
Event Object Properties:
<Object> jobInfo An object containing job information including job ID, status, message, etc. Based on the GP job object returned by the GP server with the jobParam property attached. Refer to the GP Job and the Checking job status topics in the ArcGIS REST API Documentation for more information and syntax.

This returned object can be passed into the .cancel(jobInfo) method to terminate a job.
{
  "inputs": {},
  "jobParams": <job parameters>,
  "jobId": <job id>,
  "jobStatus": <job status>,
  "messages": <an array of message text>,
  "results": {}
}

start

Fires when the execute method is called. (Added at v3.7)
Event Object Properties:
<Object> params The input job parameters.