Available with Location Referencing license.
- URL:https://<network-layer-url>/relocateEvent
- Version Introduced:10.9
Description
License:
The ArcGIS Location Referencing license is required to use this resource.
This operation allows an external system to query changes that have been made to measures in an event table during a period of time. External systems can use this information at regular intervals to synchronize themselves to route edits in the LRS Network.
Request parameters
| Parameter | Details |
|---|---|
| f | Optional parameter to specify the response format. The default response format is html. Values: html | json |
| eventName | Description: The name of the event table to be relocated. This must be a registered external event. |
| lastInvokedTime | Optional parameter to specify the time value when this tool was last run. When an external system makes a relocate event request, the date and time of that request is returned in the response (based on ArcGIS Server system time). The external system should pass the DateTime back to this call on subsequent requests to get only those changes to the LRS that occurred since the last request. If no value is provided, the events are relocated for all the route changes, constrained by the lrsTime and lastLrsTime parameters. This parameter is required for the invoker to ingest only network changes for a fixed lrsTime, as ArcGIS Location Referencing supports editing routes for future or past dates. Use of this parameter makes it more clear which edits to apply to the desired lrsTime without potentially reporting a route as changed on more than one subsequent call. For example, if a user edits a route on 1/1/2013 with changes effective on 1/1/2015, and an external system requests the network on 2/1/2013, followed by (in order) 2/1/2014, 2/2/2015, and 3/2/2015, only the third request (2/2/2015) confirms the route change. The parameter value for lastInvokedTime is a number that represents the number of milliseconds since epoch (January 1, 1970) in UTC. Syntax: lastInvokedTime=<DateTime> Example: lastInvokedTime=1609459200 (1 Jan 2021 00:00:00 GMT) |
| lrsTime | Optional parameter to specify the temporal view date on which route edits are inspected. ArcGIS Location Referencing stores routes and other network details with different representations across time. This parameter can be used to focus the time view of the network changes to be processed, which is especially useful for external systems that don't support multiple representations of the LRS network across time. For such systems, a specific time snapshot of the LRS can be requested. If no value is provided, the default is to relocate events across all route changes, constrained by the lastInvokedTime parameter if one is provided. The parameter value for lrsTime is a number that represents the number of milliseconds since epoch (January 1, 1970) in UTC. Syntax: lastLrsTime=<DateTime> Example: lastLrsTime=1609459200 (1 Jan 2021 00:00:00 GMT) |
| lastLrsTime |
Optional parameter to specify the lastLrsTime that the caller used in the previous call to this service. The provided value is used to identify route changes that are already processed for event measure location in previous invocations. This parameter value is ignored if lastInvokedTime is not specified. If no value is provided, the default is to relocate events across all route changes since the lastInvokedTime for the specified lrsTime. If the external system, in conjunction with calling the relocate measures service, also invokes the Export Network service due to the need to persist a copy of the LRS, the lastLrsTime should be the same as the lastLrsTime provided in the Export Network call. The parameter value for lastLrsTime is a number that represents the number of milliseconds since epoch (January 1, 1970) in UTC. Syntax: lastLrsTime=<DateTime> Example: lastLrsTime=1609459200 (1 Jan 2021 00:00:00 GMT) |
| outputFormat | Optional parameter that determines the data format of the output event records. The following output formats are supported:
Syntax: outputFormat=<format> Example: outputFormat="FGDB" |
| includeEventGeometries | Description: Optional parameter that determines whether event shapes are included with the output event records. This parameter is ignored unless outputFormat is JSON or FGDB. Values: true|false Note:The default value is false. |
| gdbVersion | Optional parameter to specify the geodatabase version to use. If this parameter is not specified, the published map's version is used. Syntax: gdbVersion=<version> Example: gdbVersion="user1.version1" |
Output file format
The following table defines the schema of the output file that stores the measure updates that result from route edits.
Note:
Point events have a null To_Measure to distinguish point events from line events.
| Column name | Description | Null? | Data type |
|---|---|---|---|
Event_ID | The unique identifier, as reported by the external system, which identifies the event. | N | TEXT |
New_Route_ID | The unique route identifier with which the event is associated after a route edit. | N | TEXT |
New_To_Route_ID | If the line event spans routes, this field stores the to route ID for the event after the route edit. This field is null for point events or line events that do not span routes. | Y | TEXT |
New_Route_Name | If the event is configured to support route names, this field stores the route name associated with this event after the route edit. | Y | TEXT |
New_To_Route_Name | If the line event is configured to support route names and spans routes, this field stores the to route name for the event after the route edit. This field is null for point events or line events that do not span routes. | Y | TEXT |
New_Start_Date | The new start date of the event resulting from a route edit. If null, the start date is assumed to be the earliest date supported by the external system. | Y | DATE |
New_End_Date | The new end date of the event resulting from a route edit. If null, the start date is assumed to be the latest date supported by the external system. | Y | DATE |
New_From_Measure | The new from measure of the event record resulting from a route edit. | N | TEXT |
New_To_Measure | The new to measure of the event record resulting from a route edit. This field is null for point events. | Y | TEXT |
Previous_Route_ID | The unique route identifier that the event was previously associated with before any route edit. | N | TEXT |
Previous_To_Route_ID | If a line event spans routes, this field stores the to route id for the event before the route edit. This field is null for point events or line events that do not span routes. | Y | TEXT |
Previous_Route_Name | If the event is configured to support route names, this field stores the route name associated with this event before the route edit. | Y | TEXT |
Previous_To_Route_Name | If a line event spans routes and is configured to support route names, this field stores the to route name for the event before the route edit. This field is null for point events or line events that do not span routes. | Y | TEXT |
Previous_Start_Date | The previous start date, as reported by the external system, of the event before the route edit. If null, the start date is the assumed to be the earliest date supported by the external system. | Y | DATE |
Previous_End_Date | The previous end date, as reported by the external system, of the event before the route edit. If null, the start date is the assumed to be the latest date supported by the external system. | Y | DATE |
Previous_From_Measure | The previous from measure, as reported by the external system, of the event record before the route edit. | N | TEXT |
Previous_To_Measure | The previous to measure, as reported by the external system, of the event record before the route edit. This field is null for point events. | Y | TEXT |
Example usage
The following example URL is used to relocate an event.
https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRServer/networkLayers/6/ relocateEvent?eventName=External_Point&lastInvokedTime=&lrsTime=&lastLrsTime=&outputFormat=CSV&includeEventGeometries=false&gdbVersion=user1.Version1&f=json
JSON Response syntax
The following is an example of response syntax for a statusURL.
{
"statusURL": <jobIdURL>
}
JSON Response example
Initial status response
The following example shows the statusURL that is returned with a jobIdURL that is used to make additional status calls.
{"statusURL": "https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRServer/jobs/je3d4eb30d9b1449a9fa71f7db6282959"}
Subsequent status response
The subsequent call uses the jobIdURL returned above.
{
"status": "esriJobSucceeded",
"percentComplete": 100,
"relocateEventJobResult": {
"url": <URL>,
"invokedTime": <dateTime>
}
}
The following demonstrates a response to calls using the jobIdURL returned above.
{
"status": "esriJobSucceeded",
"percentComplete": 100,
"relocateEventJobResult": {
"url": https://sampleServer/server/rest/directories/arcgisoutput/_ags_lrs_D7A3CE7F-69B8-4E2A-BFF8-0C2E28AEE3D2.json,
"invokedTime": 1610004496000
}
}