Relocate Event

URL:: https://<network-layer-url>/relocateEvent
Methods:: GET
Required Capability:: The ArcGIS Location Referencing license is required to use this resource.
Version Introduced:: 10.9

Description

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

Parameter	Details
`f` (Optional)	Specifies the response format. The default response format is `html`. Values: `html` \| `json` \| `pjson`
`eventName` (Optional)	The name of the external event registered with the LRS. If no value is provided, the `eventLocations` and `eventBehaviors` parameters are required. The `eventName` parameter value can be an external event configured with or without a connection file.
`eventLocations` (Optional)	A list of event values to be relocated. This parameter is required if the `eventName` parameter is not provided or if the provided `eventName` parameter value is an external event without a connection file. Syntax: Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 [ { // syntax of a point event to be relocated "routeId": "<routeId1>", "measure": <measure1>, "eventId": <eventId1>, // optional string or number value "fromDate": <fromDate1>, // optional date value "toDate": <toDate1> // optional date value }, { // syntax of a line event to be relocated "routeId": "<routeId2>", "fromMeasure": <measure2a>, "toMeasure": <measure2b>, "eventId": <eventId2>, // optional string or number value "fromDate": <fromDate2>, // optional date value "toDate": <toDate2> // optional date value }, { // syntax of a line event that spans multiple routes. This is valid only for networks that support lines "routeId": "<routeId3a>", "toRouteId": "<routeId3b>", "fromMeasure": <measure3a>, "toMeasure": <measure3b>, "eventId": <eventId13>, // optional string or number value "fromDate": <fromDate13>, // optional date value "toDate": <toDate13> // optional date value }, ... ]
`eventBehaviors` (Optional)	The event behaviors to be applied to relocated events. This parameter is required if the `eventName` parameter is not specified. If `eventName` is specified, then this parameter value is ignored, and the event behaviors are: Syntax: Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 9 { "calibrateRule": "<calibrationRule>", // one of type esriStayPut, esriRetire, esriMove "retireRule": "<retireRule>", // one of type esriStayPut, esriRetire, esriMove, esriSnap "reassignRule": "<reassignRule>", // one of type esriStayPut, esriRetire, esriMove, esriSnap "extendRule": "<extendRule>", // one of type esriStayPut, esriRetire, esriMove, esriCover "realignRule": "<realignRule>", // one of type esriStayPut, esriRetire, esriMove, esriSnap, esriCover "reverseRule": "<reverseRule>", // one of type esriStayPut, esriRetire, esriMove "cartoRealignRule": "<cartoRealignRule>" // one of type esriHonorRouteMeasure }
`lastInvokedTime` (Optional)	Specifies 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 clearer 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: Use dark colors for code blocksCopy `1 lastInvokedTime=<DateTime>` Example: Use dark colors for code blocksCopy `1 lastInvokedTime=1609459200 (1 Jan 2021 00:00:00 GMT)`
`lrsTime` (Optional)	Specifies 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: Use dark colors for code blocksCopy `1 lastLrsTime=<DateTime>` Example: Use dark colors for code blocksCopy `1 lastLrsTime=1609459200 (1 Jan 2021 00:00:00 GMT)`
`lastLrsTime` (optional)	Specifies 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: Use dark colors for code blocksCopy `1 lastLrsTime=<DateTime>` Example: Use dark colors for code blocksCopy `1 lastLrsTime=1609459200 (1 Jan 2021 00:00:00 GMT)`
`outputFormat` (Optional)	Determines the data format of the output event records. The following output formats are supported: FGDB—Zipped File Geodatabase. JSON CSV Syntax: Use dark colors for code blocksCopy `1 outputFormat=<format>` Example: Use dark colors for code blocksCopy `1 outputFormat="FGDB"`
`includeEventGeometries` (Optional)	Determines whether event shapes are included with the output event records. This parameter is ignored unless `outputFormat` is `JSON` or `FGDB`. This is set to `false` by default. Values: `true` \| `false`
`gdbVersion` (Optional)	Specifies the geodatabase version to use. If this parameter is not specified, the published map's version is used. Syntax: Use dark colors for code blocksCopy `1 gdbVersion=<version>` Example: Use dark colors for code blocksCopy `1 gdbVersion="user1.version1"`

f

(Optional)

Specifies the response format. The default response format is html.

Values: html | json | pjson

eventName

(Optional)

The name of the external event registered with the LRS.

If no value is provided, the eventLocations and eventBehaviors parameters are required. The eventName parameter value can be an external event configured with or without a connection file.

eventLocations

(Optional)

A list of event values to be relocated.

This parameter is required if the eventName parameter is not provided or if the provided eventName parameter value is an external event without a connection file.

Syntax:

Use dark colors for code blocksCopy
[
  {
    // syntax of a point event to be relocated
    "routeId": "<routeId1>",
    "measure": <measure1>,
    "eventId": <eventId1>, 		// optional string or number value
    "fromDate": <fromDate1>,	// optional date value
    "toDate": <toDate1> 		// optional date value
  },
  {
    // syntax of a line event to be relocated
    "routeId": "<routeId2>",
    "fromMeasure": <measure2a>,
    "toMeasure": <measure2b>,
    "eventId": <eventId2>, 	// optional string or number value
    "fromDate": <fromDate2>,	// optional date value
    "toDate": <toDate2> 	// optional date value
  },
  {
    // syntax of a line event that spans multiple routes. This is valid only for networks that support lines
    "routeId": "<routeId3a>",
    "toRouteId": "<routeId3b>",
    "fromMeasure": <measure3a>,
    "toMeasure": <measure3b>,
    "eventId": <eventId13>, 	// optional string or number value
    "fromDate": <fromDate13>,	// optional date value
    "toDate": <toDate13> 		// optional date value
  },
  ...
]

eventBehaviors

(Optional)

The event behaviors to be applied to relocated events.

This parameter is required if the eventName parameter is not specified.

If eventName is specified, then this parameter value is ignored, and the event behaviors are:

Syntax:

Use dark colors for code blocksCopy
{
  "calibrateRule": "<calibrationRule>", 	// one of type esriStayPut, esriRetire, esriMove
  "retireRule": "<retireRule>", 		// one of type esriStayPut, esriRetire, esriMove, esriSnap
  "reassignRule": "<reassignRule>", 	// one of type esriStayPut, esriRetire, esriMove, esriSnap
  "extendRule": "<extendRule>", 		// one of type esriStayPut, esriRetire, esriMove, esriCover
  "realignRule": "<realignRule>", 		// one of type esriStayPut, esriRetire, esriMove, esriSnap, esriCover
  "reverseRule": "<reverseRule>", 		// one of type esriStayPut, esriRetire, esriMove
  "cartoRealignRule": "<cartoRealignRule>" 	// one of type esriHonorRouteMeasure
}

lastInvokedTime

(Optional)

Specifies 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 clearer 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:

Use dark colors for code blocksCopy
lastInvokedTime=<DateTime>

Example:

Use dark colors for code blocksCopy
lastInvokedTime=1609459200 (1 Jan 2021 00:00:00 GMT)

lrsTime

(Optional)

Specifies 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:

Use dark colors for code blocksCopy
lastLrsTime=<DateTime>

Example:

Use dark colors for code blocksCopy
lastLrsTime=1609459200 (1 Jan 2021 00:00:00 GMT)

lastLrsTime (optional)

Specifies 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:

Use dark colors for code blocksCopy
lastLrsTime=<DateTime>

Example:

Use dark colors for code blocksCopy
lastLrsTime=1609459200 (1 Jan 2021 00:00:00 GMT)

outputFormat

(Optional)

Determines the data format of the output event records.

The following output formats are supported:

FGDB—Zipped File Geodatabase.
JSON
CSV

Syntax:

Use dark colors for code blocksCopy
outputFormat=<format>

Example:

Use dark colors for code blocksCopy
outputFormat="FGDB"

includeEventGeometries

(Optional)

Determines whether event shapes are included with the output event records. This parameter is ignored unless outputFormat is JSON or FGDB. This is set to false by default.

Values: true | false

gdbVersion

(Optional)

Specifies the geodatabase version to use. If this parameter is not specified, the published map's version is used.

Syntax:

Use dark colors for code blocksCopy
gdbVersion=<version>

Example:

Use dark colors for code blocksCopy
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.

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 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 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

Example 1

The following example URL is used to relocate an event.

Use dark colors for code blocksCopy
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

Example 2

The following example URL is used to relocate a point event without a connection file.

Use dark colors for code blocksCopy
https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRServer/networkLayers/6/relocateEvent?eventName=&eventLocations=[{“routeId”: “I90”, “measure”: 1.1}]&eventBehaviors=["calibrateRule":esriStayPut,"retireRule":esriStayPut,"reassignRule":esriStayPut,"extendRule":esriStayPut,"realignRule":esriStayPut,"reverseRule":esriStayPut,"cartoRealignRule":esriHonorRouteMeasure]&&lastInvokedTime=&lrsTime=&lastLrsTime=&outputFormat=CSV&includeEventGeometries=false&gdbVersion=user1.Version1&f=json

Example 3

The following example URL is used to relocate a line event without a connection file.

Use dark colors for code blocksCopy
https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRServer/networkLayers/6/relocateEvent?eventName=&eventLocations=[{“routeId”: “I90”, “measure”: 0,”toMeasure”:5.5}]&eventBehaviors=["calibrateRule":esriStayPut,"retireRule":esriStayPut,"reassignRule":esriStayPut,"extendRule":esriStayPut,"realignRule":esriStayPut,"reverseRule":esriStayPut,"cartoRealignRule":esriHonorRouteMeasure]&&lastInvokedTime=&lrsTime=&lastLrsTime=&outputFormat=CSV&includeEventGeometries=false&gdbVersion=user1.Version1&f=json

Example 4

The following example URL is used to relocate a spanning line event without a connection file.

Use dark colors for code blocksCopy
https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRServer/networkLayers/6/relocateEvent?eventName=&eventLocations=[{“routeId”: “I90a”, “toRouteId”:”I90b“measure”: 0,”toMeasure”:5.5}]&eventBehaviors=["calibrateRule":esriStayPut,"retireRule":esriStayPut,"reassignRule":esriStayPut,"extendRule":esriStayPut,"realignRule":esriStayPut,"reverseRule":esriStayPut,"cartoRealignRule":esriHonorRouteMeasure]&&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.

Use dark colors for code blocksCopy
{
  "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.

Use dark colors for code blocksCopy
{"statusURL": "https://sampleserver/arcgis/rest/services/MyLRS/MapServer/exts/LRServer/jobs/je3d4eb30d9b1449a9fa71f7db6282959"}

Subsequent status response

The subsequent call uses the jobIdURL returned above.

Use dark colors for code blocksCopy
{
 "status": "esriJobSucceeded",
 "percentComplete": 100,
 "relocateEventJobResult": {
  "url": <URL>,
  "invokedTime": <dateTime>
 }
}

The following demonstrates a response to calls using the jobIdURL returned above.

Use dark colors for code blocksCopy
{
 "status": "esriJobSucceeded",
 "percentComplete": 100,
 "relocateEventJobResult": {
 "url": https://sampleServer/server/rest/directories/arcgisoutput/_ags_lrs_D7A3CE7F-69B8-4E2A-BFF8-0C2E28AEE3D2.json,
 "invokedTime": 1610004496000
 }
}

Additional notes

The eventName, eventLocations, and eventBehaviors parameters are conditionally required under the following scenarios.

External event type	eventName	eventLocations	eventBehaviors
External event with connection file – registered with LRS	Required	Optional	Optional
External event with no connection file – registered with LRS	Provided	Required	Optional
External event with no connection file – registered with LRS	Not provided	Required	Required
External event not configured	Not provided	Required	Required

When providing the eventLocations parameter, the POST method should be used to send large requests. The recommended limit for the eventLocations parameter is ~25,000 events.