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`	The name of the event table to be relocated. This must be a registered external event.
`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 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: 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. 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

The name of the event table to be relocated. This must be a registered external event.

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

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.

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

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

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