- Introduction
- Concepts
- Mapping service operations
The Mapping service enables centralized governance and management of mapping definitions. In general, there could be many formats or structures for the same entity depending on its source.
Although this schema flexibility allows for better data preservation, it makes it more difficult for other applications and workflows to consume this raw ingested data. It requires them to know all available raw structures in advance before data can be consumed.
This issue is minimized by the use of a standard structure, called the "Well Known Structure" (WKS). WKS is a standard and known format that can be used by any application or workflow with only the information about this one structure.
In order for the ingested raw data to be converted into WKS, you must create a mapping definition. Mapping definitions carry the details of structural transformations of user data into WKS.
The transformations are performed by the WKS Transformation service; the WKS Transformation service is the direct consumer of mapping definitions in the system.
The Mapping service enables users to define these mapping definitions. It provides an API to create, update, and obtain previously created mapping definitions.
After a mapping definition from a given source schema to a target (WKS) schema is available, the newly ingested and updated records that conform to the source schema are transformed into the target (WKS) schema data using these definitions.
Transformation operations for a record, for example from raw to a WKS, happen in the sequential order of the operations provided in a mapping file. It is important that you place the operations in the mapping file in the correct order.
- Source schema: Refers to the original structural representation of the data that is ingested.
- Target schema: Refers to the WKS schema to which the original data will be transformed.
- Mapping definition: Contains mapping identity information and a list of mapped attributes from the original schema to the target schema.
- Mapping definition kind: Like the schema for an entity, a mapping definition also has a schema. The kind of the mapping definition uniquely defines the schema of the mapping definition.
For example, mapping kind '<authority>:mapping:mapping:1.2.3' defines the mapping schema from<authority>as having a major version of 1, a minor version of 2, and a patch version of 3.
The mapping schema kind is '<authority>.mapping:mapping:1.0.0' in the current Mapping service, and you cannot modify the mapping definition schema kind. - Mapping definition versions: They are immutable. If an existing mapping definition is updated using the PUT API, a newer version is created. The latest mapping definition version is used by default.
- Mapping definition uniqueness: The mapping definition is unique for a given major version of a source and target schema pair. A mapping definition is uniquely identified by the mapping identity information which includes:
- Mapping authority
- Mapping Kind
- Source schema details (sourceAuthority : sourceSource : sourceEntity : sourceMajorVersion)
- Target schema details (targetAuthority : targetSource : targetEntity : targetMajorVersion)
- Mapping definition scope: Mapping definitions defined using the Mapping service have a scope value INTERNAL.
- INTERNAL: A mapping definition with an INTERNAL scope is defined in a specific data partition and is available only to the users of that data partition.
- Mapping identifier: This unique string value is used to identify each mapping operation within the mapping list.
- Mapping operation: Declares how and from where the value for a given target property name is populated during WKS transformation. It is this collection of operations that maps the source raw data to target WKS data. The following tables describe the attributes of the operation and how to use them.
The Mapping service currently supports the following mapping operation types:
| Operation type | Description |
|---|---|
| COPY | Copies simple attributes or a single element of an array to a target array element. |
| COPY_SUBSTRUCTURE | Copies an entire substructure from the source property into the target property given that the source property is a json substructure . |
| RELATIONSHIP | Supports linkage of a related target record to a related parentRecord during the transformation. A raw record, called a parentRecord, maintains relationships with one or more other records, called a relatedRecord, using attributes such as "x-osdu-relationship" in the schema. Target records generated from such a parentRecord hold the relationship with the targetrRecords of the relatedRecord. |
| RELATIONSHIP_ARRAY | Used to define a relationship based on an entire array or list of source properties. |
| CONSTANT | Supports copying a static constant value to the target attribute. |
| AGGREGATE | Used to define sub operations that need to be aggregated as a single logical entity. Aggregate operations can be used for the following use cases: -Ensures the handling of complex constructs as a logical entity. Examples: vertical measurements, geo contexts, spatial location. -Gives the user the flexibility to define various mappings together to ensure the completeness of the logical entity. -Supports conditions to ensure the sanctity of the logical entity. Supported condition types are: ifAnyExists, ifAllExists, ifNotExists, and equals. |
| CONCATENATE | Concatenates multiple values. This is the use case where multiple values from the source property will be concatenated by using an operator. There are no limitations for the operator. It can be anything, such as "-" or "+", used to compute another value in the target property. Example: The two source properties, UWI and UBHI, will compute one value in the target property WellboreId. Well head is identified by UWI and all sidetrack wellbores have a UBHI ID. So each wellbore ID can be defined by concatenating UWI+UBHI. |
| COPY_ARRAY_INDEX | Copies the value of "#" in the target property. The target property captures the index value of the object. "#" indicates the index of the array where the object will be copied. |
| CONDITIONAL_PRIORITY | This container operation holds sub operations with different conditions and priorities. The conditions are evaluated on the basis of the priority of the operations. The operations are evaluated from highest priority to the lowest priority. When any of the operations succeed, all the rest of the operations with descending priority are not evaluated further. Example: The operation with priority=1 is computed first. If it succeeds, then the operations with a lower priority are not computed. |
| REFERENCE_LOOKUP | Used to transform OSDU reference data attributes. The operation searches the reference data catalogs based on the provided search parameters and then copies the retrieved reference data value to the target. |
| LOOKUP_BY_QUERY | Used to perform a lookup against master data/reference data type relationship attributes. The operation copies the retrieved reference/master data value to the target based on the search criteria provided in the mappings. |
The Mapping service provides the following conditions that you can combine with mapping operations to support the sanctity of complex logical entities:
| Condition | Description |
|---|---|
| equals | Used to validate the equality of a specific value and the value of the included source or target attributes. |
| ifAnyExists | Used to validate the existence of any one of the included source or target attributes. |
| ifAllExists | Used to validate the existence of all the included source or target attributes. |
| ifNotExists | Used to validate the non existence of all the included source or target attributes. |
- Only the AND operation is allowed to be used with conditions, such as ifAllExists, ifAnyExists, ifNotExists, and equals and not the OR operation.
- [] Denotes array operations. An operation that contains empty square brackets is not a valid operation. Only inegers, '*', and '#' are allowed inside square brackets [].
- [n] Denotes the nth index of an array, such as 1,2, or 3. This is usefule for COPY and RELATIONSHIP operations.
- [*] Denotes all indexes of the array. This is useful for COPY, RELATIONSHIP, and RELATIONSHIP_ARRAY operations.
- [#] Denotes any index of the array. The new index is calculated and appended to the array if it exists. If an array does not exist, it will be created. This is useful for operations that are combined with the AGGREGATE operation.
- [?] Denotes the specific index of the array from which the value should be copied. The operation always evaluates to the
?value which will be the index of the array object (source or target array object).
- @ Indicates that the value of the attribute mentioned in the "value" parameter should be considered from the source or target record. For example: "value": "@sourceProperty:data.wellHeadProjected.elevationFromMsl.unitKey".
- label When using a REFERENCE_LOOKUP operation or LOOKUP_BY_QUERY operation for transformation, The looked-up value can be stored in a
labeland can be called multiple times during the transformation of the given record. This avoids multiple search calls and optimizes transformation performance. Note that the scope of the label-value is limited to the current record transformation by the WKS Service. - isCaseInsensitiveExactMatch Case Insensitive Exact Match refers to the comparison that ignores the distinction between uppercase and lowercase letters. In order to perform transformation using LOOKUP_BY_QUERY operation for related reference and master data, the flexibility to perform case sensitive/insensitive lookup is required. The data manager can make a choice while doing the configuration. Adding the attribute
isCaseInsensitiveExactMatchin the mapping configuration enables a case-insensitive exact match lookup.
The following example of a source to target record transformation using a relevant mapping file explains all the previously mentioned operations and conditions as per their actual use:
Source record
{ "data": { "country": "US", "name": "Newton 2-31-Lat-1", "state": "Arizona", "NameAliases": [ { "AliasName": "Example AliasName One", "AliasNameTypeID": "namespace:reference-data--AliasNameType:RegulatoryIdentifier:", "DefinitionOrganisationID": "namespace:master-data--Organisation:SomeUniqueOrganisationID:", "EffectiveDateTime": "2020-02-13T09:13:15.55Z", "TerminationDateTime": "2020-02-13T09:13:15.55Z" }, { "AliasName": "Example AliasName Two", "AliasNameTypeID": "namespace:reference-data--AliasNameType:RegulatoryIdentifier:", "DefinitionOrganisationID": "namespace:master-data--Organisation:SomeUniqueOrganisationID:", "EffectiveDateTime": "2019-07-24T05:12:11.55Z", "TerminationDateTime": "2020-09-11T03:12:11.55Z" } ], "Measurements": [ { "EffectiveTimestamp": "2020-02-13T09:13:15.55Z", "TerminationDateTime": "2020-02-13T09:13:15.55Z" }, { "EffectiveTimestamp": "2020-02-13T09:13:15.55Z", "TerminationDateTime": "2020-02-13T09:13:15.55Z" } ], "well": { "id": "namespace:master-data--Well:6c60ceb0-3521-57b7-9bd8-e1d7c9f6623", "name": "Newton 2-31-Lat-1" }, "TrajectoryTypeID": "namespace:reference-data--WellboreTrajectoryType:Vertical:", "ResourceHostRegionIDs": [ "namespace:reference-data--OSDURegion:AWSEastUSA:", "namespace:reference-data--OSDURegion:AWSWestUSA:" ], "LogSets": [ "namespace:logSet:1ab6e370c6dd4e269243cf05b4ec5a14", "namespace:logSet:2fg4e260c8dd4e169240cf15b4ec6b36" ], "totalDepthMd": { "value": 34, "unitKey": "m" }, "elevationReference": { "elevationFromMsl": { "value": 30, "unitKey": "ft" }, "name": "KB" }, "locationWGS84": { "features": [ { "geometry": { "coordinates": [ -88.249008, 65.93041 ], "type": "Point" }, "properties": { "name": "Raw Record" }, "type": "Feature" } ], "type": "FeatureCollection" }, "wellHeadProjected": { "crsKey": "GCS_WGS_1984", "x": -12.5399, "y": 35.4635, "elevationFromMsl": { "value": 421.11, "unitKey": "m" } }, "wellHeadWgs84": { "latitude": -14.5399, "longitude": 31.4635 } }, "meta": [ { "kind": "CRS", "name": "GCS_WGS_1984", "persistableReference": "{"wkt":"GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433],AUTHORITY["EPSG",4326]]","ver":"PE_10_3_1","name":"GCS_WGS_1984","authCode":{"auth":"EPSG","code":"4326"},"type":"LBC"}", "propertyNames": [ "wellHeadProjected.x", "wellHeadProjected.y", "wellHeadWgs84.latitude", "wellHeadWgs84.longitude" ] }, { "kind": "Unit", "name": "m", "persistableReference": "{"scaleOffset":{"scale":1.0,"offset":0.0},"symbol":"m","baseMeasurement":{"ancestry":"L","type":"UM"},"type":"USO"}", "propertyNames": [ "wellHeadProjected.elevationFromMsl.value", "totalDepthMd.value" ] }, { "kind": "Unit", "name": "ft", "persistableReference": "{"scaleOffset":{"scale":0.3048,"offset":0.0},"symbol":"ft","baseMeasurement":{"ancestry":"Length","type":"UM"},"type":"USO"}", "propertyNames": [ "elevationReference.elevationFromMsl.value" ] } ], "kind": "<authority>:petrel:wellbore:1.0.6", "acl": { "viewers": [ "<acl_viewers>" ], "owners": [ "<acl_owners>" ] }, "legal": { "legaltags": [ "<legaltags>" ], "otherRelevantDataCountries": [ "US" ] } }
Mapping file
{ "mappingIdentity": { "authority": "<authority>", "sourceSchema": { "authority": "<authority>", "source": "petrel", "entityType": "wellbore", "schemaVersionMajor": 1 }, "targetSchema": { "authority": "<authority>", "source": "wks", "entityType": "wellbore", "schemaVersionMajor": 1 } }, "mappings": [ { "identifier": "name", "operations": [ { "type": "COPY ", "sourceProperty": "data.name", "targetProperty": "data.WellName" } ] }, { "identifier": "country", "operations": [ { "type": "CONCATENATE", "operator": "-", "attributes": [ { "sourceProperty": "data.country" }, { "sourceProperty": "data.state" } ], "targetProperty": "data.Country" } ] }, { "identifier": "Measurements.EffectiveTimestamp", "operations": [ { "type": "COPY", "sourceProperty": "data.Measurements[].EffectiveTimestamp", "targetProperty": "data.Measurements[].EffectiveDateTime" } ] }, { "identifier": "NameAliases", "operations": [ { "type": "COPY", "sourceProperty": "data.NameAliases[1]", "targetProperty": "data.NameAliases[0]" } ] }, { "identifier": "locationWGS84", "operations": [ { "type": "COPY_SUBSTRUCTURE", "sourceProperty": "data.locationWGS84", "targetProperty": "data.locationWGS84" } ] }, { "identifier": "WellandTrajectoryTypeId", "operations": [ { "type": "RELATIONSHIP", "sourceProperty": "data.well.id", "targetProperty": "data.WellID" }, { "type": "RELATIONSHIP", "sourceProperty": "data.TrajectoryTypeID", "targetProperty": "data.TrajectoryTypeID" } ] }, { "identifier": "ResourceHostRegionIDs", "operations": [ { "type": "RELATIONSHIP_ARRAY", "sourceProperty": "data.ResourceHostRegionIDs[]", "targetProperty": "data.ResourceHostRegionIDs[]" } ] }, { "identifier": "LogSet", "operations": [ { "type": "RELATIONSHIP", "sourceProperty": "data.LogSets[1]", "targetProperty": "data.LogSet.ids[0]" } ] }, { "identifier": "data.elevationReference.name", "operations": [ { "type": "AGGREGATE", "operations": [ { "type": "COPY_ARRAY_INDEX", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID" }, { "type": "COPY", "sourceProperty": "data.elevationReference.name", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID" }, { "type": "COPY", "sourceProperty": "data.elevationReference.elevationFromMsl.value", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement" }, { "type": "COPY", "sourceProperty": "data.elevationReference.elevationFromMsl.unitKey", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID" }, { "type": "CONSTANT", "value": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:ELEV:", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID", "andCondition": [ { "type": "ifAllExists", "attributes": [ { "sourceProperty": "data.elevationReference.name" }, { "sourceProperty": "data.elevationReference.elevationFromMsl.value" }, { "sourceProperty": "data.elevationReference.elevationFromMsl.unitKey" } ] } ] }, { "type": "CONDITIONAL_PRIORITY", "operations": [ { "type": "COPY", "sourcProperty": "data.name", "targetProperty": "data.VerticalMeasurements[#].VerticalCRSID", "priority": 1, "andCondition": [ { "type": "equals", "attributes": [ { "sourceProperty": "data.name", "value": "KB" } ] } ] }, { "type": "CONSTANT", "value": "Test Value", "targetProperty": "data.VerticalMeasurements[#].VerticalCRSID", "priority": 2 } ] } ] } ] }, { "identifier": "data.totalDepthMd.value", "operations": [ { "type": "AGGREGATE", "operations": [ { "type": "CONSTANT", "value": "Total Depth MD", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID" }, { "type": "COPY_ARRAY_INDEX", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID" }, { "type": "COPY", "sourceProperty": "data.totalDepthMd.value", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement", "andCondition": [ { "type": "equals", "attributes": [ { "value": "ft", "sourceProperty": "data.totalDepthMd.unitKey" } ] } ] }, { "type": "COPY", "sourceProperty": "data.totalDepthMd.unitKey", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID" }, { "type": "CONSTANT", "value": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:MD:", "targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID", "andCondition": [ { "type": "ifAnyExists", "attributes": [ { "sourceProperty": "data.totalDepthMd.value" }, { "sourceProperty": "data.totalDepthMd.unitKey" } ] } ] } ] } ] }, { "identifier": "data.SpatialLocation", "operations": [ { "type": "AGGREGATE", "operations": [ { "type": "CONSTANT", "value": "{{NAMESPACE}}:reference-data--SpatialGeometryType:Point:0", "targetProperty": "data.SpatialLocation.SpatialGeometryTypeID", "andCondition": [ { "type": "ifAllExists", "attributes": [ { "sourceProperty": "data.wellHeadProjected.x" }, { "sourceProperty": "data.wellHeadProjected.y" }, { "sourceProperty": "data.wellHeadProjected.elevationFromMsl.value" } ] } ] }, { "type": "CONSTANT", "value": "{{NAMESPACE}}:reference-data--SpatialGeometryType:Point:0", "targetProperty": "data.SpatialLocation.SpatialGeometryTypeID", "andCondition": [ { "type": "ifAllExists", "attributes": [ { "sourceProperty": "data.wellHeadWgs84.latitude" }, { "sourceProperty": "data.wellHeadWgs84.longitude" }, { "sourceProperty": "data.wellHeadWgs84.elevationFromMsl.value" } ] } ] }, { "type": "COPY", "sourceProperty": "data.wellHeadProjected.crsKey", "targetProperty": "data.SpatialLocation.AsIngestedCoordinates.CoordinateReferenceSystemID" }, { "type": "COPY", "sourceProperty": "data.wellHeadProjected.x", "targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.coordinates[0]" }, { "type": "COPY", "sourceProperty": "data.wellHeadProjected.y", "targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.coordinates[1]" }, { "type": "COPY", "sourceProperty": "data.wellHeadProjected.elevationFromMsl.value", "targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.coordinates[2]" }, { "type": "CONSTANT", "value": "Point", "targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.type", "andCondition": [ { "type": "ifAllExists", "attributes": [ { "sourceProperty": "data.wellHeadProjected.x" }, { "sourceProperty": "data.wellHeadProjected.y" }, { "sourceProperty": "data.wellHeadProjected.elevationFromMsl.value" } ] } ] }, { "type": "CONSTANT", "value": "Point", "targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.type", "andCondition": [ { "type": "ifAllExists", "attributes": [ { "sourceProperty": "data.wellHeadWgs84.latitude" }, { "sourceProperty": "data.wellHeadWgs84.longitude" }, { "sourceProperty": "data.wellHeadWgs84.elevationFromMsl.value" } ] } ] }, { "type": "CONSTANT", "value": "Feature", "targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].type", "andCondition": [ { "type": "ifAnyExists", "attributes": [ { "sourceProperty": "data.wellHeadProjected.x" }, { "sourceProperty": "data.wellHeadProjected.y" }, { "sourceProperty": "data.wellHeadProjected.elevationFromMsl.value" } ] } ] }, { "type": "CONSTANT", "value": "FeatureCollection", "targetProperty": "data.SpatialLocation.AsIngestedCoordinates.type", "andCondition": [ { "type": "ifAnyExists", "attributes": [ { "sourceProperty": "data.wellHeadProjected.x" }, { "sourceProperty": "data.wellHeadProjected.y" }, { "sourceProperty": "data.wellHeadProjected.elevationFromMsl.value" } ] } ] }, { "type": "COPY", "sourceProperty": "data.wellHeadWgs84.longitude", "targetProperty": "data.SpatialLocation.Wgs84Coordinates.features[#].geometry.coordinates[0]" }, { "type": "COPY", "sourceProperty": "data.wellHeadWgs84.latitude", "targetProperty": "data.SpatialLocation.Wgs84Coordinates.features[#].geometry.coordinates[1]" }, { "type": "CONSTANT", "value": "Point", "targetProperty": "data.SpatialLocation.Wgs84Coordinates.features[#].geometry.type", "andCondition": [ { "type": "ifAllExists", "attributes": [ { "sourceProperty": "data.wellHeadWgs84.latitude" }, { "sourceProperty": "data.wellHeadWgs84.longitude" } ] } ] }, { "type": "CONSTANT", "value": "Feature", "targetProperty": "data.SpatialLocation.Wgs84Coordinates.features[#].type", "andCondition": [ { "type": "ifAnyExists", "attributes": [ { "sourceProperty": "data.wellHeadWgs84.latitude" }, { "sourceProperty": "data.wellHeadWgs84.longitude" } ] } ] }, { "type": "CONSTANT", "value": "FeatureCollection", "targetProperty": "data.SpatialLocation.Wgs84Coordinates.type", "andCondition": [ { "type": "ifAnyExists", "attributes": [ { "sourceProperty": "data.wellHeadWgs84.latitude" }, { "sourceProperty": "data.wellHeadWgs84.longitude" } ] } ] } ] } ] } ] }
Target record
{ "data": { "WellName": "Newton 2-31-Lat-1", "Country": "US-Arizona", "NameAliases": [ { "AliasName": "Example AliasName Two", "AliasNameTypeID": "namespace:reference-data--AliasNameType:RegulatoryIdentifier:", "DefinitionOrganisationID": "namespace:master-data--Organisation:SomeUniqueOrganisationID:", "EffectiveDateTime": "2019-07-24T05:12:11.55Z", "TerminationDateTime": "2020-09-11T03:12:11.55Z" } ], "Measurements": [ { "EffectiveDateTime": "2020-02-13T09:13:15.55Z" }, { "EffectiveDateTime": "2020-02-13T09:13:15.55Z" } ], "WellID": "namespace:master-data--Well:6c60ceb0-3521-57b7-9bd8-e1d7c9f6623", "TrajectoryTypeID": "namespace:reference-data--WellboreTrajectoryType:Vertical:", "ResourceHostRegionIDs": [ "namespace:reference-data--OSDURegion:AWSEastUSA:", "namespace:reference-data--OSDURegion:AWSWestUSA:" ], "LogSets": { "ids": [ "namespace:logSet:2fg4e260c8dd4e169240cf15b4ec6b36" ] }, "VerticalMeasurements": [ { "VerticalMeasurementID": 0, "VerticalMeasurement": 30, "VerticalMeasurementTypeID": "KB", "VerticalMeasurementPathID": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:ELEV:", "VerticalMeasurementUnitOfMeasureID": "ft", "VerticalCRSID": "KB" }, { "VerticalMeasurementID": 1, "VerticalMeasurementTypeID": "Total Depth MD", "VerticalMeasurement": 34, "VerticalMeasurementPathID": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:MD:", "VerticalMeasurementUnitOfMeasureID": "m" } ], "locationWGS84": { "features": [ { "geometry": { "coordinates": [ -88.249008, 65.93041 ], "type": "Point" }, "properties": { "name": "Raw Record" }, "type": "Feature" } ], "type": "FeatureCollection" }, "SpatialLocation": { "AsIngestedCoordinates": { "type": "FeatureCollection", "CoordinateReferenceSystemID": "GCS_WGS_1984", "SpatialGeometryTypeID": "{{NAMESPACE}}:reference-data--SpatialGeometryType:Point:0", "persistableReferenceCrs": "{"wkt":"GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433],AUTHORITY["EPSG",4326]]","ver":"PE_10_3_1","name":"GCS_WGS_1984","authCode":{"auth":"EPSG","code":"4326"},"type":"LBC"}", "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -12.5399, 35.4635, 421.11 ] } } ] }, "Wgs84Coordinates": { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -14.5399, 31.4635 ] } } ] } } }, "meta": [ { "kind": "CRS", "name": "GCS_WGS_1984", "persistableReference": "{"wkt":"GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433],AUTHORITY["EPSG",4326]]","ver":"PE_10_3_1","name":"GCS_WGS_1984","authCode":{"auth":"EPSG","code":"4326"},"type":"LBC"}", "propertyNames": [ "SpatialLocation.Wgs84Coordinates" ] }, { "kind": "Unit", "name": "ft", "persistableReference": "{"scaleOffset":{"scale":0.3048,"offset":0.0},"symbol":"ft","baseMeasurement":{"ancestry":"Length","type":"UM"},"type":"USO"}", "propertyNames": [ "VerticalMeasurements[0].VerticalMeasurement" ] }, { "kind": "Unit", "name": "m", "persistableReference": "{"scaleOffset":{"scale":0.3048,"offset":0.0},"symbol":"m","baseMeasurement":{"ancestry":"Length","type":"UM"},"type":"USO"}", "propertyNames": [ "VerticalMeasurements[1].VerticalMeasurement" ] } ], "kind": "<authority>:wks:wellbore:1.0.6", "acl": { "viewers": [ "<acl_viewers>" ], "owners": [ "<acl_owners>" ] }, "legal": { "legaltags": [ "<legaltags>" ], "otherRelevantDataCountries": [ "US" ] } }
The COPY operation supports the copying of simple attributes or a single element of an array to a target array element.
In this example an attribute in an array element is mapped to a target array element. This renaming must be applied to all the indexes of the array. The size of the array in the target record remains the same as in the raw source record.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"Measurements": [
{
"EffectiveTimestamp": "2020-02-13T09:13:15.55Z"
},
{
"EffectiveTimestamp": "2019-11-10T11:15:40.55Z"
}
]
}
}
|
{
"mappings": [{
"identifier": "data.Measurements.EffectiveTimestamp",
"operations": [
{
"type": "COPY",
"sourceProperty": "data.Measurements[*].EffectiveTimestamp",
"targetProperty": "data.VerticalMeasurements[*].EffectiveDateTime"
}
]
}]
}
|
{
"data": {
"VerticalMeasurements" : [
{
"EffectiveDateTime" : "2020-02-13T09:13:15.55Z"
},
{
"EffectiveDateTime" : "2019-11-10T11:15:40.55Z"
}
]
}
}
|
In this example, a complete array element is mapped to a target array. This mapping changes only the name of the array. The index attributes are copied as it is from RAW to WKS record. The size of the WKS target record remains the same as it is in the raw source record.
| Raw record | Mapping definition | Target record |
|---|---|---|
```
{
"data": {
"Measurements": [
{
"EffectiveTimestamp": "2020-02-13T09:13:15.55Z",
"TerminationDateTime": "2022-11-10T11:15:40.55Z"
},
{
"EffectiveTimestamp": "2019-11-20T09:15:15.55Z",
"TerminationDateTime": "2022-11-10T11:15:40.55Z"
}
]
}
}
```
|
```
{
"mappings": [{
"identifier": "data.Measurements",
"operations": [
{
"type": "COPY",
"sourceProperty": "data.Measurements[*]",
"targetProperty": "data.VerticalMeasurements[*]"
}
]
}]
}
```
|
```
{
"data": {
"VerticalMeasurements" : [
{
"EffectiveTimestamp": "2020-02-13T09:13:15.55Z",
"TerminationDateTime": "2022-11-10T11:15:40.55Z"
},
{
"EffectiveTimestamp": "2019-11-20T09:15:15.55Z",
"TerminationDateTime": "2022-11-10T11:15:40.55Z"
}
]
}
}
```
|
The COPY_SUBSTRUCTURE operation is used to copy an entire substructure from the source property into the target property, given that the source property is a json substructure. In the following example, the whole substructure of sourceProperty LOCATION_WGS84 is copied as it is to the targetProperty locationWGS84.
| Raw record | Mapping definition | Target record |
|---|---|---|
```
{
"data": {
"LOCATION_WGS84": {
"features": [
{
"geometry": {
"coordinates": [
-88.249008,
65.93041
],
"type": "Point"
},
"properties": {
"name": "Raw Record"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
}
}
```
|
```
{
"mappings": [{
"identifier": "locationWGS84",
"operations": [
{
"type": "COPY_SUBSTRUCTURE",
"sourceProperty": "data.LOCATION_WGS84",
"targetProperty": "data.locationWGS84"
}
]
}]
}
```
|
```
{
"data": {
"locationWGS84": {
"features": [
{
"geometry": {
"coordinates": [
-88.249008,
65.93041
],
"type": "Point"
},
"properties": {
"name": "Raw Record"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
}
}
```
|
The COPY operation with the arrayIndex property is an operation that copies the value of a specific array index to an object in the target array.
The arrayIndex schema provides a condition that is used to evaluate from which index in the array the value should be copied. When the condition is met, the value will be copied.
It works with the [?] array type used to denote the specific index of the array from which the value should be copied. The operation always evaluates to the ? value which is the index of the array object.
If the arrayIndex attribute in the operation has targetProperty defined, then ? indicates the index of the target object.
The arrayIndex is computed on the complete array object. So, the pre-requisite is that the array object mapping (AGGREGATE operations) is already provided before the COPY operation with arrayIndex.
Used outside AGGREGATE new attribute outside the array will be created, and the value will be copied there.
In the following example when all three AGGREGATE operations are complete, the COPY operation with arrayIndex is evaluated.
The value of
"@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID"will be copied to the targetdata.DefaultVerticalMeasurementIDin a newly created attribute, only if the condition in thearrayIndexis evaluated. This condition returns an array index value.In the
arrayIndex, you should define the condition that will help evaluate the array index[?]from which the value of@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementIDshould be taken for aCOPYoperation.The condition returns the
array index(?)where the value in"targetProperty": "data.VerticalMeasurements[?].VerticalMeasurementID"is equal to the valueMeasured_From.
Now that the value of arrayIndex (?) is evaluated, the COPY operation can evaluate the value to copy using the following statement:"type": "COPY", "targetProperty": "data.DefaultVerticalMeasurementID", "value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",The value of
"@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID"will be copied to a new attribute calledDefaultVerticalMeasurementIDoutside the vertical measurement array.In the following example, the
arrayIndexcondition evaluates to the zeroth index in the array. Then a new attribute,DefaultVerticalMeasurementID, is created with the value copied fromVerticalMeasurementIDfrom the zeroth index.
| Raw record | Mapping definition | Target record |
|---|---|---|
```
{
"data": {
"ELEV_RT": 42.51,
"MD_TD": 2790.0,
"TVD_TD": 2543.27
}
}
```
|
```
{
"mappings": [
{
"identifier": "data.VerticalMeasurements",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "Measured_From",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.ELEV_RT",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--VerticalMeasurementType:RT:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--VerticalMeasurementPath:ELEV:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:",
"targetProperty": "data.VerticalMeasurements[#].VerticalCRSID"
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "TD-Original",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.MD_TD",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--VerticalMeasurementType:TD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--VerticalMeasurementPath:MD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalCRSID",
"value": "partition_id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
}
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "TVD",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.TVD_TD",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--VerticalMeasurementType:TD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--VerticalMeasurementPath:TVD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "CONSTANT",
"value": "partition_id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalCRSID",
"value": "partition_id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
}
}
]
},
{
"type": "COPY",
"targetProperty": "data.DefaultVerticalMeasurementID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalMeasurementID",
"value": "Measured_From"
}
}
]
}
]
}
```
|
```
{
"data": {
"VerticalMeasurements": [
{
"VerticalMeasurementID": "Measured_From",
"VerticalMeasurement": 42.51,
"VerticalMeasurementTypeID": "partition_id:reference-data--VerticalMeasurementType:RT:",
"VerticalMeasurementPathID": "partition_id:reference-data--VerticalMeasurementPath:ELEV:",
"VerticalMeasurementUnitOfMeasureID": "partition_id:reference-data--UnitOfMeasure:m:",
"VerticalCRSID": "partition_id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
},
{
"VerticalMeasurementID": "TD-Original",
"VerticalMeasurement": 2790.0,
"VerticalMeasurementTypeID": "partition_id:reference-data--VerticalMeasurementType:TD:",
"VerticalMeasurementPathID": "partition_id:reference-data--VerticalMeasurementPath:MD:",
"VerticalMeasurementUnitOfMeasureID": "partition_id:reference-data--UnitOfMeasure:m:",
"VerticalReferenceID": "Measured_From"
},
{
"VerticalMeasurementID": "TVD",
"VerticalMeasurement": 2543.27,
"VerticalMeasurementTypeID": "partition_id:reference-data--VerticalMeasurementType:TD:",
"VerticalMeasurementPathID": "partition_id:reference-data--VerticalMeasurementPath:TVD:",
"VerticalMeasurementUnitOfMeasureID": "partition_id:reference-data--UnitOfMeasure:m:",
"VerticalReferenceID": "Measured_From"
}
],
"DefaultVerticalMeasurementID": "Measured_From"
}
}
```
|
In the following example the COPY operation with arrayIndex inside the last AGGREGATE operation is pointing to the element that has the ReferenceID property and not a VerticalCRSID.
The value of
"@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID"is copied to the targetdata.VerticalMeasurements[#].VerticalReferenceID
in the last object in the target array only if the condition in the arrayIndex is evaluated. This condition returns an array index value.In the
arrayIndex, you should define the condition that will help evaluate the array index[?]from which the value of@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementIDshould be used for aCOPYoperation.The condition returns the
array index(?)where the value in"targetProperty": "data.VerticalMeasurements[?].VerticalMeasurementTypeID"is equal to the valuepartition-id:reference-data--VerticalMeasurementType:DL:.
Now that the value of arrayIndex (?) is evaluated, the COPY operation can evaluate the value to copy using the following statement:"type": "COPY", "targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID", "value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID"The value of
"@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID"is copied to the last element in the vertical measurement array in a new attribute calledVerticalReferenceID.In the following example, the
arrayIndexcondition in the last AGGREGATE operation evaluates to the second index in the array. Then theVerticalReferenceIDproperty is created in the last object with the value copied fromVerticalMeasurementIDfrom the second index.
| Raw record | Mapping definition | Target record |
|---|---|---|
```
{
"data": {
"ELEV_MSL": 0,
"ELEV_DL": 25.0,
"TVD_MLS": 76.5,
"TVDVRS_TD": 1300.0,
"TVDZDP_TD": 1325.0
}
}
```
|
```
{
"mappings": [
{
"identifier": "data.VerticalMeasurements",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "MSL EPSG:5714",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.ELEV_MSL",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:MSL:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:ELEV:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:",
"targetProperty": "data.VerticalMeasurements[#].VerticalCRSID"
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "DF 25 m",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.ELEV_DL",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:DL:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:ELEV:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalCRSID",
"value": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
}
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "SF 76.5 m",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.TVD_MLS",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:MLS:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalCRSID",
"value": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
}
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "TD TVDVRS",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.TVDVRS_TD",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:TD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalCRSID",
"value": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
}
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "TD TVDZDP",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.TVDZDP_TD",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:TD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalMeasurementTypeID",
"value": "partition-id:reference-data--VerticalMeasurementType:DL:"
},
"andCondition": [
{
"type": "ifNotExists",
"attributes": [
{
"targetProperty": "data.VerticalMeasurements[#].VerticalCRSID"
}
]
}
]
}
]
}
]
}
]
}
```
|
{
"VerticalMeasurements": [
{
"VerticalMeasurementID": "MSL EPSG:5714",
"VerticalMeasurement": 0,
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:MSL:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:ELEV:",
"VerticalCRSID": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
},
{
"VerticalMeasurementID": "DF 25 m",
"VerticalMeasurement": 25.0,
"VerticalMeasurementUnitOfMeasureID": "partition-id:reference-data--UnitOfMeasure:m:",
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:DL:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:ELEV:",
"VerticalReferenceID": "MSL EPSG:5714"
},
{
"VerticalMeasurementID": "SF 76.5 m",
"VerticalMeasurement": 76.5,
"VerticalMeasurementUnitOfMeasureID": "partition-id:reference-data--UnitOfMeasure:m:",
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:MLS:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"VerticalReferenceID": "MSL EPSG:5714"
},
{
"VerticalMeasurementID": "TD TVDVRS",
"VerticalMeasurement": 1300.0,
"VerticalMeasurementUnitOfMeasureID": "partition-id:reference-data--UnitOfMeasure:m:",
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:TD:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"VerticalReferenceID": "MSL EPSG:5714"
},
{
"VerticalMeasurementID": "TD TVDZDP",
"VerticalMeasurement": 1325.0,
"VerticalMeasurementUnitOfMeasureID": "partition-id:reference-data--UnitOfMeasure:m:",
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:TD:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"VerticalReferenceID": "DF 25 m"
}
]
}
|
Use the CONSTANT operation to copy a static constant value to the target attribute.
In this example, the value of targetProperty is a constant provided in the value attribute. No data is taken from the raw record. valueType is an optional attribute to define the type of value. Supported valuetypes are - integer, float, string, boolean.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"UWI": "FQ2129",
"UBHI": "0"
}
}
|
{
"mappings": {
"identfier": "Constants_LookUp_VerticalMeasurementPathID",
"operations": [
{
"type": "CONSTANT",
"value": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:MD:",
"targetProperty": "data.VerticalMeasurements[0].VerticalMeasurementPathID"
},
{
"type": "CONSTANT",
"value": "Total Depth MD",
"targetProperty": "data.VerticalMeasurements[1].VerticalMeasurementID"
},
{
"type": "CONSTANT",
"value": "123",
"valueType": "integer"
"targetProperty": "data.VerticalMeasurements[2].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "2020-02-13T09:13:15.55Z",
"valueType": "string"
"targetProperty": "data.VerticalMeasurements[3].EffectiveTimestamp"
}
]
}
}
|
{
"data": {
"VerticalMeasurements": [
{
"VerticalMeasurementPathID": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:MD:"
},
{
"VerticalMeasurementID": "Total Depth MD"
},
{
"VerticalMeasurement": 123
},
{
"EffectiveTimestamp": "2020-02-13T09:13:15.55Z"
}
]
}
}
|
Operations that include square brackets [] in target or source property attribute is an array operation. An operation that contains empty square brackets is not a valid operation. Only integers, '*', and '#' are allowed inside the square brackets [].
- [n] Denotes the nth index of an array, such as 1,2, or 3. This is usefule for COPY and RELATIONSHIP operations.
- [*] Denotes all indexes of the array. This is useful for COPY, RELATIONSHIP, and RELATIONSHIP_ARRAY operations.
- [#] Denotes any index of the array. The new index is calculated and appended to the array if it exists. If an array does not exist, it will be created. This is useful for operations that are combined with the AGGREGATE operation.
- [?] Denotes the specific index of the array from which the value should be copied. The operation always evaluates to the
?value which will be the index of the array object (source or target array object).
In this example, a particular index of an attribute is mapped to a target. The size of the array depends on the specific mapping provided. For this use case, the array in target record will be 1 because only one index element mapping is provided.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"Measurements": [
{
"EffectiveTimestamp": "2020-02-13T09:13:15.55Z"
}
]
}
}
|
{
"mappings": [{
"identifier": "data.Measurements.EffectiveTimestamp",
"operations": [
{
"type": "COPY",
"sourceProperty": "data.Measurements[0].EffectiveTimestamp",
"targetProperty": "data.VerticalMeasurements[0].EffectiveDateTime"
}
]
}]
}
|
{
"data": {
"VerticalMeasurements": [
{
"EffectiveDateTime": "2020-02-13T09:13:15.55Z"
}
]
}
}
|
In this example, constant values are mapped to the target record's VerticalMeasurementPathID and VerticalMeasurementID attributes.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"Measurements": [
{
"VerticalMeasurementID": "Example VerticalMeasurementID",
"EffectiveTimestamp": "2020-02-13T09:13:15.55Z",
"VerticalMeasurement": 12345.6,
"TerminationDateTime": "2020-02-13T09:13:15.55Z"
}
]
}
}
|
{
"mappings": [{
"identifier": "Constants_LookUp_VerticalMeasurementPathID",
"operations": [
{
"type": "CONSTANT",
"value": "datapartitionId:reference-data--VerticalMeasurementPath:MD:",
"targetProperty": "data.VerticalMeasurements[0].VerticalMeasurementPathID"
},
{
"type": "CONSTANT",
"value": "Total Depth MD",
"targetProperty": "data.VerticalMeasurements[1].VerticalMeasurementID"
}
]
}]
}
|
{
"data": {
"VerticalMeasurements": [
{
"VerticalMeasurementPathID": "datapartitionId:reference-data--VerticalMeasurementPath:MD:"
},
{
"VerticalMeasurementID": "Total Depth MD"
}
]
}
}
|
At this example, a simple attribute is mapped to a specific index of an array. Because this is a very specific use case to map a simple attribute to an array element, the size of the array would remain "1" as one mapping is provided in the example below.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"totalDepthMd": {
"value": 34,
"unitKey": "m"
}
}
}
|
{
"mappings": [{
"identifier": "SimpleAttribute_VerticalMeasurementID",
"operations": [
{
"type": "COPY",
"sourceProperty": "data.totalDepthMd.value",
"targetProperty": "data.VerticalMeasurements[0].VerticalMeasurement"
}
]
}]
}
|
{
"data": {
"VerticalMeasurements": [
{
"VerticalMeasurement": 34
}
]
}
}
|
In this example, the Marker Name attribute from each object of Markers array is mapped to Formation Name array in target property.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"Wellbore Name": "Ahuroa-4",
"Name": "Marker1",
"Markers": [
{
"Marker Name": "Check1",
"Marker Type": "Biostratigraphy"
},
{
"Top Depth": "2700",
"Marker Name": "Check2",
"Marker Type": "Biostratigraphy"
},
{
"Top Depth": "3230",
"Marker Name": "Check3",
"Marker Type": "Biostratigraphy"
},
{
"Top Depth": "3244",
"Marker Name": "Check4",
"Marker Type": "Biostratigraphy"
},
{
"Top Depth": "3300",
"Marker Name": "Check5",
"Marker Type": "Biostratigraphy"
}
]
|
{
"mappings": [
{
"identifier": "data.Markers.MarkerName",
"operations": [
{
"type": "COPY",
"sourceProperty": "data.Markers[*].Marker Name",
"targetProperty": "data.TargetMarkers.Formation Name[*]"
}
]
}
]
}
|
{
"data": {
"TargetMarkers": {
"Formation Name": [
"Check1",
"Check2",
"Check3",
"Check4",
"Check5"
]
}
}
}
|
The CONCATENATE operation concatenates multiple values. This is useful when multiple values from the source property need to be concatenated to compute another value using an operator.
Operators such as "-" or "+", can be used to compute another value in the target property.
In this example, the values from the sourceProperty attribute are concatenated using the operator attribute to the target property.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"UWI": "FQ2129",
"UBHI": "0431"
}
}
|
{
"mappings": [{
"identifier": "data.WellboreId",
"operations": [
{
"type": "CONCATENATE",
"operator": "-",
"attributes": [
{
"sourceProperty": "data.UWI"
},
{
"sourceProperty": "data.UBHI"
}
],
"targetProperty": "data.WellboreId"
}
]
}]
}
|
{
"data": {
"WellboreId": "FQ2129-0431"
}
}
|
Used to define sub operations that need to be aggregated as a single logical entity.
Aggregate operations can be used for the following use cases:
- Ensures the handling of complex constructs as a logical entity. Examples: vertical measurements, geo contexts, spatial location.
- Gives the user the flexibility to define various mappings together to ensure the completeness of the logical entity.
- Supports conditions to ensure the sanctity of the logical entity. Supported condition types are: ifAnyExists, ifAllExists, ifNotExists, and equals.
This is a mapping operation used to aggregate a set of sub operations as a single logical entity to apply to data.
This example illustrates the application of AGGREGATE with regards to elevation measurement data.
In the below example, andCondition will evaluate if any of the attributes "data.totalDepthMd.value" OR "data.totalDepthMd.unitKey" exists in the raw record , then the value of array element "data.VerticalMeasurements[#].VerticalMeasurementPathID" will be "ABC:reference-data--VerticalMeasurementPath:MD:"
Note: The value of hash (#) in target path for all child operations within a parent AGGREGATE operation, is evaluated once and used for all child operations ensuring that all aggregagated operation are copied at the same index of the array in the transformed record.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"totalDepthMd": {
"value": 34,
"unitKey": "m"
},
"elevationReference": {
"elevationFromMsl": {
"value": 30,
"unitKey": "ft"
},
"name": "KB"
}
}
}
|
{
"mappings": [
{
"identifier": "data.totalDepthMd.value",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "Total Depth MD",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "COPY",
"sourceProperty": "data.totalDepthMd.value",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "COPY",
"sourceProperty": "data.totalDepthMd.unitKey",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "ABC:reference-data--VerticalMeasurementPath:MD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID",
"andCondition": [
{
"type": "ifAnyExists",
"attributes": [
{
"sourceProperty": "data.totalDepthMd.value"
},
{
"sourceProperty": "data.totalDepthMd.unitKey"
}
]
}
]
}
]
}
]
}
]
}
|
{
"data": {
"VerticalMeasurements" : [ {
"VerticalMeasurementTypeID" : "Total Depth MD",
"VerticalMeasurement" : 34,
"VerticalMeasurementUnitOfMeasureID" : "m",
"VerticalMeasurementPathID" : "ABC:reference-data--VerticalMeasurementPath:MD:"
}
}
|
The following example illustrates the application of the AGGREGATE operation with regards to spatial location data. We provide an example usage of the "equals" condition based on the operation in the following aggregate operation. This means that the operation will execute only if the equals condition is validated. If there is a hash (#) index in the sourceProperty path with the "equals" condition, then all the indexes are validated by the equality check, and if a match is found, that index value is used in place of the hash(#) in the sourceProperty of the operation.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"wellHeadProjected": {
"crsKey": "GCS_WGS_1984",
"x": -12.5399,
"y": 35.4635,
"elevationFromMsl": {
"value": 421.11,
"unitKey": "m"
}
},
"wellHeadWgs84": {
"latitude": -14.5399,
"longitude": 31.4635
}
},
"meta": [
{
"kind": "CRS",
"name": "GCS_WGS_1984",
"persistableReference": "{\"wkt\":\"GEOGCS[\"GCS_WGS_1984\",
DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_1984\",6378137.0,
298.257223563]],PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",
0.0174532925199433],AUTHORITY[\"EPSG\",4326]]\",
\"ver\":\"PE_10_3_1\",\"name\":\"GCS_WGS_1984\",
\"authCode\" :{\"auth\":\"EPSG\",
\"code\":\"4326\"},\"type\":\"LBC\"}",
"propertyNames": [
"wellHeadProjected.x",
"wellHeadProjected.y",
"wellHeadProjected.elevationFromMsl.value",
"wellHeadWgs84.latitude",
"wellHeadWgs84.longitude"
]
},
{
"kind": "Unit",
"name": "m",
"persistableReference": "{\"scaleOffset\":{\"scale\":1.0,
\"offset\":0.0},\"symbol\":\"m\",\"baseMeasurement\":
{\"ancestry\":\"L\",\"type\":\"UM\"},\"type\":\"USO\"}",
"propertyNames": [
"wellHeadProjected.x",
"wellHeadProjected.y",
"wellHeadProjected.elevationFromMsl.value",
"wellHeadWgs84.latitude",
"wellHeadWgs84.longitude"
]
}
]
}
|
{
"mappings": [
{
"identifier": "data.SpatialLocation",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONSTANT",
"value": "{{NAMESPACE}}:reference-data--SpatialGeometryType:Point:0",
"targetProperty": "data.SpatialLocation.SpatialGeometryTypeID",
"andCondition": [
{
"type": "ifAllExists",
"attributes": [
{
"sourceProperty": "data.wellHeadProjected.x"
},
{
"sourceProperty": "data.wellHeadProjected.y"
},
{
"sourceProperty": "data.wellHeadProjected.elevationFromMsl.value"
}
]
}
]
},
{
"type": "CONSTANT",
"value": "{{NAMESPACE}}:reference-data--SpatialGeometryType:Point:0",
"targetProperty": "data.SpatialLocation.SpatialGeometryTypeID",
"andCondition": [
{
"type": "ifAllExists",
"attributes": [
{
"sourceProperty": "data.wellHeadWgs84.latitude"
},
{
"sourceProperty": "data.wellHeadWgs84.longitude"
},
{
"sourceProperty": "data.wellHeadWgs84.elevationFromMsl.value"
}
]
}
]
},
{
"type": "COPY",
"sourceProperty": "data.wellHeadProjected.crsKey",
"targetProperty": "data.SpatialLocation.AsIngestedCoordinates.CoordinateReferenceSystemID"
},
{
"type": "COPY",
"sourceProperty": "data.wellHeadProjected.x",
"targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.coordinates[0]"
},
{
"type": "COPY",
"sourceProperty": "data.wellHeadProjected.y",
"targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.coordinates[1]"
},
{
"type": "COPY",
"sourceProperty": "data.wellHeadProjected.elevationFromMsl.value",
"targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.coordinates[2]"
},
{
"type": "CONSTANT",
"value": "Point",
"targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.type",
"andCondition": [
{
"type": "ifAllExists",
"attributes": [
{
"sourceProperty": "data.wellHeadProjected.x"
},
{
"sourceProperty": "data.wellHeadProjected.y"
},
{
"sourceProperty": "data.wellHeadProjected.elevationFromMsl.value"
}
]
}
]
},
{
"type": "CONSTANT",
"value": "Point",
"targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].geometry.type",
"andCondition": [
{
"type": "ifAllExists",
"attributes": [
{
"sourceProperty": "data.wellHeadWgs84.latitude"
},
{
"sourceProperty": "data.wellHeadWgs84.longitude"
},
{
"sourceProperty": "data.wellHeadWgs84.elevationFromMsl.value"
}
]
}
]
},
{
"type": "CONSTANT",
"value": "Feature",
"targetProperty": "data.SpatialLocation.AsIngestedCoordinates.features[#].type",
"andCondition": [
{
"type": "ifAnyExists",
"attributes": [
{
"sourceProperty": "data.wellHeadProjected.x"
},
{
"sourceProperty": "data.wellHeadProjected.y"
},
{
"sourceProperty": "data.wellHeadProjected.elevationFromMsl.value"
}
]
}
]
},
{
"type": "CONSTANT",
"value": "FeatureCollection",
"targetProperty": "data.SpatialLocation.AsIngestedCoordinates.type",
"andCondition": [
{
"type": "ifAnyExists",
"attributes": [
{
"sourceProperty": "data.wellHeadProjected.x"
},
{
"sourceProperty": "data.wellHeadProjected.y"
},
{
"sourceProperty": "data.wellHeadProjected.elevationFromMsl.value"
}
]
}
]
},
{
"type": "COPY",
"sourceProperty": "data.wellHeadWgs84.longitude",
"targetProperty": "data.SpatialLocation.Wgs84Coordinates.features[#].geometry.coordinates[0]"
},
{
"type": "COPY",
"sourceProperty": "data.wellHeadWgs84.latitude",
"targetProperty": "data.SpatialLocation.Wgs84Coordinates.features[#].geometry.coordinates[1]"
},
{
"type": "CONSTANT",
"value": "Point",
"targetProperty": "data.SpatialLocation.Wgs84Coordinates.features[#].geometry.type",
"andCondition": [
{
"type": "ifAllExists",
"attributes": [
{
"sourceProperty": "data.wellHeadWgs84.latitude"
},
{
"sourceProperty": "data.wellHeadWgs84.longitude"
}
]
}
]
},
{
"type": "CONSTANT",
"value": "Feature",
"targetProperty": "data.SpatialLocation.Wgs84Coordinates.features[#].type",
"andCondition": [
{
"type": "ifAnyExists",
"attributes": [
{
"sourceProperty": "data.wellHeadWgs84.latitude"
},
{
"sourceProperty": "data.wellHeadWgs84.longitude"
}
]
}
]
},
{
"type": "CONSTANT",
"value": "FeatureCollection",
"targetProperty": "data.SpatialLocation.Wgs84Coordinates.type",
"andCondition": [
{
"type": "ifAnyExists",
"attributes": [
{
"sourceProperty": "data.wellHeadWgs84.latitude"
},
{
"sourceProperty": "data.wellHeadWgs84.longitude"
}
]
}
]
}
]
}
]
}
]
}
|
{
"data": {
"SpatialLocation": {
"SpatialGeometryTypeID": "{{NAMESPACE}}:reference-data--SpatialGeometryType:Point:0",
"AsIngestedCoordinates": {
"CoordinateReferenceSystemID": "GCS_WGS_1984",
"features": [
{
"geometry": {
"coordinates": [
-12.5399,
35.4635,
421.11
],
"type": "Point"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
},
"Wgs84Coordinates": {
"features": [
{
"geometry": {
"coordinates": [
31.4635,
-14.5399
],
"type": "Point"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
}
}
}
|
Copies the value of "#" in the target property. The target property captures the index value of the object. "#" indicates the index of the array where the object will be copied.
In the following example, a new attribute, VerticalMeasurementID, is added to the target WKS record that captures the array index of the object.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"ELEV_MSL": 0,
"ELEV_DL": 25.0,
"TVD_MLS": 76.5,
"TVDVRS_TD": 1300.0,
"TVDZDP_TD": 1325.0
}
}
|
{
"mappings": [
{
"identifier": "data.VerticalMeasurements",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "COPY_ARRAY_INDEX",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.ELEV_MSL",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:MSL:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:ELEV:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:",
"targetProperty": "data.VerticalMeasurements[#].VerticalCRSID"
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "COPY_ARRAY_INDEX",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.ELEV_DL",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:DL:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:ELEV:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalCRSID",
"value": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
}
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "COPY_ARRAY_INDEX",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.TVD_MLS",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:MLS:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalCRSID",
"value": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
}
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "COPY_ARRAY_INDEX",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.TVDVRS_TD",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:TD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalCRSID",
"value": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
}
}
]
},
{
"type": "AGGREGATE",
"operations": [
{
"type": "COPY_ARRAY_INDEX",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
},
{
"type": "COPY",
"sourceProperty": "data.TVDZDP_TD",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--UnitOfMeasure:m:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementType:TD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID"
},
{
"type": "CONSTANT",
"value": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID"
},
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalMeasurementTypeID",
"value": "partition-id:reference-data--VerticalMeasurementType:DL:"
}
}
]
}
]
}
]
}
|
{
"VerticalMeasurements": [
{
"VerticalMeasurementID": 0,
"VerticalMeasurement": 0,
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:MSL:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:ELEV:",
"VerticalCRSID": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
},
{
"VerticalMeasurementID": 1,
"VerticalMeasurement": 25.0,
"VerticalMeasurementUnitOfMeasureID": "partition-id:reference-data--UnitOfMeasure:m:",
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:DL:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:ELEV:",
"VerticalReferenceID": 0
},
{
"VerticalMeasurementID": 2,
"VerticalMeasurement": 76.5,
"VerticalMeasurementUnitOfMeasureID": "partition-id:reference-data--UnitOfMeasure:m:",
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:MLS:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"VerticalReferenceID": 0
},
{
"VerticalMeasurementID": 3,
"VerticalMeasurement": 1300.0,
"VerticalMeasurementUnitOfMeasureID": "partition-id:reference-data--UnitOfMeasure:m:",
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:TD:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"VerticalReferenceID": 0
},
{
"VerticalMeasurementID": 4,
"VerticalMeasurement": 1325.0,
"VerticalMeasurementUnitOfMeasureID": "partition-id:reference-data--UnitOfMeasure:m:",
"VerticalMeasurementTypeID": "partition-id:reference-data--VerticalMeasurementType:TD:",
"VerticalMeasurementPathID": "partition-id:reference-data--VerticalMeasurementPath:TVD:",
"VerticalReferenceID": 1
}
]
}
|
The following example illustrates the application of the AGGREGATE operation with the CONDITIONAL_PRIORITY sub operation.
CONDITIONAL_PRIORITY is a container operation that holds sub operations with different conditions and priorities.
The conditions are evaluated on the basis of the priority of the operations. The operations are evaluated from highest priority to the lowest priority. When any of the operations succeed, all the rest of the operations with descending priority are not evaluated further.
In the following example, if data.WEL_ELEVATION_REF equals "KB", then COPY data.WEL_ELEVATION_REF to VerticalCRSID, else add a constant value to VerticalCRSID.
If operation with priority 1 is true, the rest will not be evaluated. If priority 1 is false, the operation with priority 2 is evaluated.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"name": "MIDLAND FARMS EAST",
"elevationReference": "KB",
"unit": "FT",
}
}
|
{
"mappings": [{
"identifier": "data.VerticalMeasurements1",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONDITIONAL_PRIORITY",
"operations": [
{
"type": "COPY",
"sourcProperty": "data.elevationReference",
"targetProperty": "data.VerticalMeasurements[#].VerticalCRSID",
"priority": 1,
"andCondition": [
{
"type": "equals",
"attributes": [
{
"sourceProperty": "data.elevationReference",
"value": "KB"
}
]
}
]
},
{
"type": "CONSTANT",
"value": "Test Value",
"targetProperty": "data.VerticalMeasurements[#].VerticalCRSID",
"priority": 2
}
]
}
]
}
]
}
]
}
|
{
"data": {
"VerticalMeasurements": [
{
"VerticalCRSID": "KB"
}
]
}
}
|
In the following example, if attr1 exists || attr2 equals "test", then COPY attr1 to target_attr, else if attr3 exists, then COPY attr3 to target_attr.
If the operation with priority 1 (If attr1 exists) is true, the rest will not be evaluated. If priority 1 is false, the operation with priority 2 (attr2 equals "test") is evaluated. If priority 2 is also false, then operation with priority 3 (if attr3 exists) is evaluated.
| Raw record | Mapping definition | Target record |
|---|---|---|
{
"data": {
"attr3": "value",
"attr4": "testValue",
"attr5": "testValueValue"
}
}
|
{
"mappings": [{
"identifier": "data.VerticalMeasurements",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "CONDITIONAL_PRIORITY",
"operations": [
{
"type": "COPY",
"sourceProperty": "data.attr1",
"targetProperty": "data.VerticalMeasurements[#].target_attr",
"priority": 1,
"andCondition": [
{
"type": "ifAnyExists",
"attributes": [
{
"sourceProperty": "data.attr1"
}
]
}
]
},
{
"type": "COPY",
"sourceProperty": "data.attr1",
"targetProperty": "data.VerticalMeasurements[#].target_attr",
"priority": 2,
"andCondition": [
{
"type": "equals",
"attributes": [
{
"sourceProperty": "data.attr2",
"value": "test"
}
]
}
]
},
{
"type": "COPY",
"sourceProperty": "data.attr3",
"targetProperty": "data.VerticalMeasurements[#].target_attr",
"priority": 3,
"andCondition": [
{
"type": "ifAnyExists",
"attributes": [
{
"sourceProperty": "data.attr3"
}
]
}
]
}
]
},
{
"type": "COPY",
"sourceProperty": "data.attr4",
"targetProperty": "data.VerticalMeasurements[#].target_attr1"
},
{
"type": "COPY",
"sourceProperty": "data.attr5",
"targetProperty": "data.VerticalMeasurements[#].target_attr2"
}
]
}
]
}]
}
|
{
"data": {
"VerticalMeasurements": [
{
"target_attr": "value",
"target_attr1": "testValue",
"target_attr2": "testValueValue"
}
]
}
}
|
This section provides some use cases related to the RELATIONSHIP and RELATIONSHIP_ARRAY operations.
| Use Cases | Mapping definition | Raw record | Target record |
|---|---|---|---|
When the record ID mentioned in the "WellID" attribute of the raw record does not exist, then the targetrecord will still contain that record ID in the "WellID" attribute as it is. |
{
"type": "RELATIONSHIP",
"sourceProperty": "data.WellID",
"targetProperty": "data.WellID"
}
|
{
"data":
{
"WellID": "slb-osdu-prod-des-prod-testing:well:89bc3631d56740d899e7cc8fa69d2ee6"
}
}
|
{
"data":
{
"WellID": "slb-osdu-prod-des-prod-testing:well:89bc3631d56740d899e7cc8fa69d2ee6"
}
}
|
When record ID mentioned in the "WellID" attribute of the raw record exists,
but the equivalent WKS ID of this record does not exist, then the
the target record will contain the generated WKS ID
appended with ":". This denotes the latest
version of the generated WKS record. Note that only the record ID of
this WKS record is generated and not the actual WKS record.
The actual WKS record will also have the same record ID whenever
it is generated by the WKS service.
|
{
"data":
{
"WellID": "slb-osdu-prod-des-prod-testing:wellbore:b5bdf34863e84a12a7347110d4164b4a:1628051435348558"
}
}
|
{
"data":
{
"WellID": "$GENERATED_WKS_RECORD_ID:"
}
}
| |
When the record ID mentioned in the "WellID" attribute of a raw record exists
and the equivalent WKS ID of this record ID also exists, then
the target record will contain the equivalent WKS ID appended with
the equivalent WKS version.
|
{
"data":
{
"WellID": "slb-osdu-prod-des-prod-testing:wellbore:techlog-
C9536975-92FC-462D-8288-8CC9408B0027--
C6452ED2-528C-4B1B-BA24-06DE2158465B
:1622040982279528"
}
}
|
|
| Use Case | Mapping definition | Raw record | Target record |
|---|---|---|---|
When the record IDs in the "ResourceHostRegionIDs" attribute of a raw record do not exist,
then the target record will still contain these record IDs as it is in the
"ResourceHostRegionIDs" attribute.
|
{
"type": "RELATIONSHIP_ARRAY",
"sourceProperty": "data.ResourceHostRegionIDs[*]",
"targetProperty": "data.ResourceHostRegionIDs[*]"
}
|
{
"data": {
"ResourceHostRegionIDs": [
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:1615982504113772",
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:2515222514254785"
]
}
}
|
{
"data": {
"ResourceHostRegionIDs": [
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:1615982504113772",
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:2515222514254785"
]
}
}
|
When the record IDs mentioned in the "ResourceHostRegionIDs" attribute of a raw record exist
but the equivalent WKS ID of these record IDs do not exist, then the
the target record will contain the generated WKS
IDs appended with ":". This denotes the latest
version of the generated WKS record. Note that only the record ID of
this WKS record will be generated and not the actual WKS record.
The actual WKS record will also have the same record ID when
it is generated by the WKS service.
|
{
"type": "RELATIONSHIP_ARRAY",
"sourceProperty": "data.ResourceHostRegionIDs[*]",
"targetProperty": "data.ResourceHostRegionIDs[*]"
}
|
{
"data": {
"ResourceHostRegionIDs": [
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:1615982504113772",
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:2515222514254785"
]
}
}
|
{
"data": {
ResourceHostRegionIDs": [
"$GENERATED_WKS_ID:",
"$GENERATED_WKS_ID:"
]
}
}
|
When the record IDs in the "ResourceHostRegionIDs" attribute of a raw record exist
and the equivalent WKS ID of these record IDs also exist, then
the target record will contain the equivalent WKS ID appended with
the equivalent WKS version.
|
{
"type": "RELATIONSHIP_ARRAY",
"sourceProperty": "data.ResourceHostRegionIDs[*]",
"targetProperty": "data.ResourceHostRegionIDs[*]"
}
|
{
"data": {
"ResourceHostRegionIDs": [
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:1615982504113772",
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:2515222514254785"
]
}
}
|
{
"data": {
"ResourceHostRegionIDs": [
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:wks-
9f934e460e823c13ffec05964ecc860a4f27eec3.slb.wks.wellbore.1
:1622106262273254",
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:wks-
7f349e450e823c13ffec05964ecc860a4f17eec3.slb.wks.wellbore.1
:1221106362223151"
]
}
}
|
| Use Case | Mapping definition | Raw record | Target record |
|---|---|---|---|
When the record ID in the "data.relationships.well.id" of a raw record does not exist,
then the target record will still contain that record ID as it is at
data.relationships.well.ids[0].
|
{
"type": "RELATIONSHIP",
"sourceProperty": "data.relationships.well.id",
"targetProperty": "data.relationships.well.ids[0]"
}
|
{
"data":
{
"relationships":
{
"well":
{
"id": "slb-osdu-prod-des-prod-testing:well:89bc3631d56740d899e7cc8fa69d2ee6",
"name": "North Dakota Well"
}
}
}
}
|
{
"data":
{
"relationships":
{
"well":
{
"ids": [
"slb-osdu-prod-des-prod-testing:well:89bc3631d56740d899e7cc8fa69d2ee6"
]
}
}
}
}
|
When the record ID in the "RegionID" attribute of a raw record exists
but the equivalent WKS ID of the record does not exist, then the
the target record will contain the generated WKS
ID appended with ":". This denotes the latest
version of the generated WKS record. Note that only the record ID for
this WKS record is generated and not the actual WKS record.
The actual WKS record will also have the same record ID whenever
it is generated by the WKS service.
|
{
"type": "RELATIONSHIP",
"sourceProperty": "data.RegionID",
"targetProperty": "data.ResourceHostRegionIDs[0]"
}
|
{
"data":
{
"RegionID": "slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:161598250411377"
}
}
|
{
"data":
{
ResourceHostRegionIDs": [
"$GENERATED_WKS_RECORD_ID:"
]
}
}
|
When the record ID in the "RegionID" attribute of raw record exists
and the equivalent WKS ID also exists, then the
the target record will contain the equivalent WKS ID appended with
the equivalent WKS version.
|
{
"type": "RELATIONSHIP",
"sourceProperty": "data.RegionID",
"targetProperty": "data.ResourceHostRegionIDs[0]"
}
|
{
"data": {
"RegionID": "slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:AWSEastUSA:161598250411377"
}
}
|
{
"data": {
ResourceHostRegionIDs": [
"slb-osdu-prod-des-prod-testing:reference-data--OSDURegion:wks-
9f934e460e823c13ffec05964ecc860a4f27eec3.slb.wks.wellbore.1
:1622106262273254"
]
}
}
|
| Use cases | Mapping definition | Raw record | Target record |
|---|---|---|---|
When the record ID in data.relationships.well.ids[0] of a raw record does not exist,
then the target Record will still contain that record ID as it is in
"WellID" attribute.
|
{
"type": "RELATIONSHIP",
"sourceProperty": "data.relationships.well.ids[0]",
"targetProperty": "data.WellID"
}
|
{
"data": {
"relationships": {
"well": {
"ids": [
"slb-osdu-prod-des-prod-testing:well:89bc3631d56740d899e7cc8fa69d2ee6"
]
}
}
}
}
|
{
"data": {
"WellID": "slb-osdu-prod-des-prod-testing:well:89bc3631d56740d899e7cc8fa69d2ee6"
}
}
}
|
When the record ID in the "BasinIDs" attribute of a raw record exists
but the equivalent WKS ID does not exist, then the target record will
contain the generated WKS ID appended with ":". This denotes the latest
version of generated WKS record. Note that only the record ID of
this WKS record is generated and not the actual WKS record.
The actual WKS record will also have the same record ID whenever
it is generated by the WKS service.
|
{
"type": "RELATIONSHIP",
"sourceProperty": "data.BasinIDs[0]",
"targetProperty": "data.WellID"
}
|
{
"data": {
"BasinIDs":[
"slb-osdu-prod-des-prod-testing:master-data--Basin:74ft4512f50710d812e7cd8aa54d3ee8"
]
}
}
|
{
"data": {
"BasinID": "$GENERATED_WKS_RECORD_ID:"
}
}
|
When the record ID in the "WellID" attribute of a raw record exists
and the equivalent WKS ID of this record also exists, then
the target record will contain the equivalent WKS ID appended with
the equivalent WKS version.
|
{
"type": "RELATIONSHIP",
"sourceProperty": "data.InitialOperators[0]",
"targetProperty": "data.InitialOperatorID"
}
|
{
"data": {
"InitialOperators":[
"slb-osdu-prod-des-prod-testing:master-data--Organisation:74ft4512f50710d812e7cd8aa54d3ee8:1628051435348558"
]
}
}
|
{
"data": {
"InitialOperatorID": "slb-osdu-prod-des-prod-testing:master-data--Organisation:wks-
9f934e460e823c13ffec05964ecc860a4f27eec3.slb.wks.wellbore.1
:1622106262273254"
}
}
|
The RELATIONSHIP operation can also be used under an AGGREGATE operation using the # whose value will be evaluated dynamically.
For more information on how # is evaluated for AGGREGATE, refer to AGGREGATE section. (AGGREGATE, COPY_ARRAY_INDEX, CONDITIONAL_PRIORITY operations).
When # is used for relationship transformations, the value of # is provided by the target aggregated array.
The following combinations are supported:
#intargetPropertyonly#in bothsourcePropertyandtargetProperty
The transformation behavior for relationship operator given related data id, remains as described before Here data contains two arrays with related data ids i.e. 'data.relationships.Block.ids' and 'data.relationships.Quadrant.ids', Each related data id needs to be transformed as per "RELATIONSHIP" Operation. The 'related data id' at 'data.relationships.Block.ids[0]' will be transformed and assigned to available index position of target GeoContexts[] array's to GeoPoliticalEntityID and the constant value will be assigned to same index position of target GeoContexts[] array's to GeoTypeID.
| Mapping definition | Raw record | Target record |
|---|---|---|
[
{
"identifier": "Quadrant",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "RELATIONSHIP",
"sourceProperty": "data.relationships.Quadrant.ids[0]",
"targetProperty": "data.GeoContexts[#].GeoPoliticalEntityID"
},
{
"type": "CONSTANT",
"value": " |
"data": {
"relationships.Block.ids": [
" |
{
"data": {
"GeoContexts": [
{
"GeoPoliticalEntityID": " |
The transformation behavior for a relationship operator, given related data ID, remains as described before. When '#' is used in both the source and target properties as shown in this example: '#' helps compute the next available array index position in the target where the transformed related data object ID will be assigned, and same index position will be used while reading the related ID to be transformed from the source array. So, the target array '#' value determined the array index value for the source array.
- Here, the first AGGREGATE operation is creating data.GeoContexts[] and adding "GeoPoliticalEntityID" and "GeoTypeID" at the 0th index of the GeoContext[] array after transforming the source data available at the data.relationships.Quadrant.ids[0] index. Note the array index '0' in data.relationships.Quadrant.ids[0] is used as per '#' evaluated for the target GeoContext[] array.
- During execution of the second AGGREGATE operation, the # value will be incremented by the count of 1. As the 0th element in data.GeoContexts[] is already present, it will increment the # value to 1 and then "GeoPoliticalEntityID" and "GeoTypeID" are added to the 1st index after transforming the source data available at data.relationships.Quadrant.ids[1] index. Note that the array index '1' in data.relationships.Quadrant.ids[1] is used as per '#' evaluated for target GeoContext[] array.
| Mapping definition | Raw record | Target record |
|---|---|---|
[
{
"identifier": "Block",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "RELATIONSHIP",
"sourceProperty": "data.relationships.Block.ids[#]",
"targetProperty": "data.GeoContexts[#].GeoPoliticalEntityID"
},
{
"type": "CONSTANT",
"value": " |
"data": {
"relationships":{
"Block":{
"ids":[
" |
{
"data": {
"GeoContexts": [
{
"GeoPoliticalEntityID": " |
The operation searches the reference data catalogs based on the provided search parameters and copies the retrieved reference data value to the target. The use cases that follow are related to REFERENCE_LOOKUP operation.
In this example, the value of the attribute to search is passed using the sourceProperty path and a constant in the mapping. Here, VerticalMeasurementTypeID is populated by searching for the Reference Data ID from the VerticalMeasurementType catalog for the code provided in the 'ALIAS_NAME' source attribute. VerticalMeasurementPathID is populated by searching for the Reference Data ID for the constant "Elevation" from the VerticalMeasurementPath catalog.
| Mapping definition | Raw record | Target record |
|---|---|---|
{
"mappings": [
{
"identifier": "data.VerticalMeasurements",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "REFERENCE_LOOKUP",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementType:1.0.0",
"queryParam": {
"Code": "@sourceProperty:data.ALIAS_NAME"
},
"returnedField": "id"
}
},
{
"type": "REFERENCE_LOOKUP",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementPath:1.0.0",
"queryParam": {
"Name": "Elevation"
},
"returnedField": "id"
}
}
]
}
]
}
]
}
|
"data": {
"ELEVATION": 4900,
"API": "Z001",
"REFERENCE_ELEVATION": 3000,
"ELEVATION_REFERENCE": "KellyBushing",
"UWI": "Z001",
"WEL_ELEVATION_REF": "GR",
"ALIAS_NAME": "GL"
}
|
{
"data": {
"VerticalMeasurements": [
{
"VerticalMeasurementTypeID": "{{NAMESPACE}}:reference-data--VerticalMeasurementType:GroundLevel:",
"VerticalMeasurementPathID": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:ELEV:"
}
]
},
"meta": null
}
|
In this example, the REFERENCE_LOOKUP operation is used in two ways:
- Inside AGGREGATE: This operation is used to look up the ID of VerticalMeasurementPath and VerticalMeasurementType in each measurement array element (kelly bushing and ground level measurements).
- With label: In this case the reference catalog based look up value (ID, code, name, etc.) is stored in a label and referred to later as shown for assigning VerticalMeasurementUnitOfMeasureID and DefaultVerticalMeasurementID.
Note: The looked up value is stored in the label and can be called multiple times during the transformation of the given record. The scope of the label-value is limited to the record transformation.
| Mapping definition | Raw record | Target record |
|---|---|---|
{
"mappings": [{
"identifier": "referenceID_elevation_ref",
"operations": [{
"type": "REFERENCE_LOOKUP",
"label": "RDVID_elevation_ref",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementType:1.0.0",
"queryParam": {
"Code": "@sourceProperty:data.ELEVATION_REFERENCE"
},
"returnedField": "id"
}
}
]
}, {
"identifier": "referenceID_UOM",
"operations": [{
"type": "REFERENCE_LOOKUP",
"label": "label_UOM",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementUnitOfMeasure:1.0.0",
"queryParam": {
"Code": "@sourceProperty:data.UNIT"
},
"returnedField": "id"
}
}
]
}, {
"identifier": "data.VerticalMeasurements",
"operations": [{
"type": "AGGREGATE",
"operations": [{
"type": "COPY_ARRAY_INDEX",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
}, {
"type": "REFERENCE_LOOKUP",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementPath:1.0.0",
"queryParam": {
"Name": "Elevation"
},
"returnedField": "id"
}
}, {
"type": "REFERENCE_LOOKUP",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementType:1.0.0",
"queryParam": {
"Code": "@sourceProperty:data.ELEVATION_REFERENCE"
},
"returnedField": "id"
}
}, {
"type": "COPY",
"sourceProperty": "data.REFERENCE_ELEVATION",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
}, {
"type": "COPY",
"value": "@label:label_UOM",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
}
]
}
],
"andCondition": [{
"type": "ifAllExists",
"attributes": [{
"sourceProperty": "data.REFERENCE_ELEVATION"
}
]
}
]
}, {
"identifier": "data.VerticalMeasurement",
"operations": [{
"type": "AGGREGATE",
"operations": [{
"type": "COPY_ARRAY_INDEX",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementID"
}, {
"type": "COPY",
"sourceProperty": "data.GROUND_ELEVATION",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurement"
}, {
"type": "REFERENCE_LOOKUP",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementType:1.0.0",
"queryParam": {
"Code": "GroundLevel"
},
"returnedField": "id"
}
}, {
"type": "REFERENCE_LOOKUP",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementPath:1.0.0",
"queryParam": {
"Name": "Elevation"
},
"returnedField": "id"
}
}, {
"type": "COPY",
"value": "@label:label_UOM",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementUnitOfMeasureID"
}
]
}
]
}, {
"identifier": "data.DefaultVerticalMeasurementID",
"operations": [{
"type": "COPY",
"targetProperty": "data.DefaultVerticalMeasurementID ",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalMeasurementTypeID",
"value": "@label:RDVID_elevation_ref"
}
}
]
}
]
}
|
"data": {
"UNIT": "FT",
"ELEVATION_REFERENCE": "KellyBushing",
"REFERENCE_ELEVATION": 2990,
"GROUND_ELEVATION": 4000
}
|
{
"data": {
"VerticalMeasurements": [{
"VerticalMeasurementID": 0,
"VerticalMeasurementPathID": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:ELEV",
"VerticalMeasurementTypeID": "{{NAMESPACE}}:reference-data--VerticalMeasurementType:KellyBushing:",
"VerticalMeasurement": 2990,
"VerticalMeasurementUnitOfMeasureID": "{{NAMESPACE}}:reference-data--UnitOfMeasure:FT"
}, {
"VerticalMeasurementID": 1,
"VerticalMeasurement": 4000,
"VerticalMeasurementTypeID": "{{NAMESPACE}}:reference-data--VerticalMeasurementType:GroundLevel:",
"VerticalMeasurementPathID": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:ELEV",
"VerticalMeasurementUnitOfMeasureID": "{{NAMESPACE}}:reference-data--UnitOfMeasure:FT"
}
],
"DefaultVerticalMeasurementID ": 0
},
"meta": null
}
|
In cases where a single query parameter may not be able to uniquely resolve a reference data value, you can look up the reference data using multiple query filters. The Reference Lookup operator allows you to specify multiple query parameters that is "ANDed" together to lookup the reference data values. Following example shows: The DefaultVerticalMeasurementID is populated by searching for the Reference Data ID from the VerticalMeasurementType catalog for the code provided in the 'WEL_ELEVATION_REF' source attribute AND the AliasName provided in the 'ALIAS_NAME' attribute and the constant value 'GRL'.
| Mapping definition | Raw record | Target record |
|---|---|---|
{
"mappings": [
{
"identifier": "data.VerticalMeasurements",
"operations": [
{
"type": "AGGREGATE",
"operations": [
{
"type": "REFERENCE_LOOKUP",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementTypeID",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementType:1.0.0",
"queryParam": {
"Code": "@sourceProperty:data.ELEVATION_REFERENCE"
},
"returnedField": "id"
}
},
{
"type": "REFERENCE_LOOKUP",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementPath:1.0.0",
"queryParam": {
"Name": "Elevation"
},
"returnedField": "id"
}
}
]
}
]
},
{
"identifier": "referenceID_elevation_ref0",
"operations": [
{
"type": "REFERENCE_LOOKUP",
"targetProperty": "data.DefaultVerticalMeasurementID",
"query": {
"kind": "osdu:wks:reference-data--VerticalMeasurementType:1.0.0",
"queryParam": {
"Code": "@sourceProperty:data.WEL_ELEVATION_REF",
"AliasName": [
"@sourceProperty:data.ALIAS_NAME",
"GRL"
]
},
"returnedField": "id"
}
}
]
}
]
}
|
"data": {
"ELEVATION_REFERENCE": "KellyBushing",
"WEL_ELEVATION_REF": "GroundLevel",
"ALIAS_NAME": "GL"
}
|
{
"data": {
"VerticalMeasurements": [
{
"VerticalMeasurementTypeID": "{{NAMESPACE}}:reference-data--VerticalMeasurementType:KellyBushing:",
"VerticalMeasurementPathID": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:ELEV:"
}
],
"DefaultVerticalMeasurementID": "{{NAMESPACE}}:reference-data--VerticalMeasurementType:GroundLevel:"
},
"meta": null
}
|
This single operation gives the user the ability to lookup for either master data or reference data.- Below mentioned are some use cases related to LOOKUP_BY_QUERY operation:
If the user wants to perform a lookup against master data/reference data type relationship attributes, user can use this operation as shown. Here a user needs to provide the search criteria based on which lookup is to be done for related master/reference data. A query using raw record input c=value can also be formed using {{@sourceProperty:data.RAW_ATTRIBUTE_NAME}}. Here, KickOffWellbore in the transformed WKS would be populated based on below 3 criterias:
- Where FacilityID is a constant value, FPSO-09-Aug-22-B2 AND
- Where AliasNameTypeID is a constant value, "{{NAMESPACE}}:reference-data--AliasNameType:RegulatoryIdentifier" for the given AliasName which would be populated using the name attribute from the raw record AND
- Where AliasNameTypeID is a constant value, "{{NAMESPACE}}:reference-data--AliasNameType:Wellbore Number" for the given AliasName, "wellbore-12A"
- Here {{NAMESPACE}} is only placeholder which will be replaced, others is part of syntax
| Mapping definition | Raw record | Target record |
|---|---|---|
[
{
"identifier": "LOOKUP_on_MasterData",
"operations": [
{
"type": "LOOKUP_BY_QUERY",
"targetProperty": "data.WellID",
"lookup": {
"kind": "osdu:wks:master-data--Wellbore:1.0.0",
"query": "data.FacilityID:\"FPSO-09-Aug-22-B2\" AND nested(data.NameAliases, (AliasName:\"{{@sourceProperty:data.name}}\" AND AliasNameTypeID:\"{{NAMESPACE}}:reference-data--AliasNameType:RegulatoryIdentifier\")) AND nested(data.NameAliases, (AliasName:\"wellbore-12A\" AND AliasNameTypeID:\"{{NAMESPACE}}:reference-data--AliasNameType:Wellbore Number\"))",
"returnedField": "id"
}
}
]
}
]
|
"data": {
"name": "Ex_Name"
}
|
{
"data": {
"WellID": "namespace:master-data--Organisation:1e2ab9dd60364ae697e34ef24b228d2b:"
}
}
|
As per OSDU documentation, Organization is both a reference and master entity. Hence, user can use DefinitionOrganisationID attribute of the NameAlias block to refer either to master data or reference data. By this mapping, user can first lookup against master data using the query in the lookup block but if queried Organization value was not found in master data, then user can perform a lookup against reference data.
If the first LOOKUP_BY_QUERY operation succeeds, label masterLookupIdOfOrganisation gets assigned the looked-up value and DefinitionOrganizationID gets a value from master data type 'Organization'.
If the first LOOKUP_BY_QUERY fails, label masterLookupIdOfOrganisation gets assigned a null value.
The second LOOKUP_BY_QUERY has an 'andCondition' that ensures that this query is evaluated only if label masterLookupIdOfOrganisation is a null value, meaning first query had failed and DefinitionOrganizationID is not assigned a value from master data catalog.
When the second LOOKUP_By_QUERY gets evaluated, DefinitionOrganizationID gets a value from the Reference data type 'Organization'.
| Mapping Definition | Raw Record | Target Record |
|---|---|---|
[
{
"identifier": "LOOKUP_on_MasterData",
"operations": [
{
"type": "LOOKUP_BY_QUERY",
"targetProperty": "data.NameAlias[#].DefinitionOrganisationID",
"label": "masterLookupIdOfOrganisation",
"lookup": {
"kind": "osdu:wks:reference-data--OrganisationType:1.0.0",
"query": "nested(data.NameAliases, (AliasName:\"{{@sourceProperty:data.Company}}\" AND AliasNameTypeID:\"{{NAMESPACE}}:reference-data--AliasNameType:IndustryName:\")) AND nested(data.NameAliases, (AliasName:\"1234\" AND AliasNameTypeID:\"{{NAMESPACE}}:reference-data--AliasNameType:Industry Code\"))",
"returnedField": "id"
}
},
{
"type": "LOOKUP_BY_QUERY",
"targetProperty": "data.NameAlias[#].DefinitionOrganisationID",
"lookup": {
"kind": "osdu:wks:reference-data--OrganisationType:1.0.0",
"query": "data.Name:{{@sourceProperty:data.Company}}",
"returnedField": "id"
},
"andCondition": [
{
"type": "equals",
"attributes": [
{
"label:masterLookupIdOfOrganisation",
"value" : ""
}
]
}
]
}
]
}
]
|
"data": {
"Company": "Ex_organization name"
}
|
{
"data": {
"NameAliases": [
{
"DefinitionOrganisationID": "{{NAMESPACE}}:master-data--Organisation:SomeUniqueOrganisationID:"
}
]
}
}
|
In the example below, as the isCaseInsensitiveExactMatch attribute is set to true, a case-insensitive exact match search is executed. For instance, if a record contains the Code as either Groundlevel or GROUNDLEVEL, the corresponding record ID is retrieved, without considering the letter case.
Note: If there are multiple records that have Code as Groundlevel and GROUNDLEVEL, the operation is skipped.
| Mapping Definition | Raw Record | Target Record |
|---|---|---|
```
[
{
"identifier": "LOOKUP_on_MasterData",
"operations": [
{
"type": "LOOKUP_BY_QUERY",
"targetProperty": "data.DefaultVerticalMeasurementID",
"lookup": {
"kind": "osdu:wks:reference-data--VerticalMeasurementType:1.0.0",
"query": "data.Code:\"{{@sourceProperty:data.WEL_ELEVATION_REF}}\"",
"returnedField": "id",
"isCaseInsensitiveExactMatch": true
},
}
]
}
]
```
|
```
"data": {
"WEL_ELEVATION_REF": "GroundLevel"
}
```
|
```
{
"data": {
"DefaultVerticalMeasurementID": "{{NAMESPACE}}:reference-data--VerticalMeasurementType:GroundLevel:"
}
}
```
|
Note:
- To use the exact match query to search records based on a precise value please refer to the Search Service Tutorial
- Using both
.keywordin query andisCaseInsensitiveExactMatchin the operation is not allowed. Either a case-sensitive exact match with.keywordin query or a case-insensitive exact match lookup withisCaseInsensitiveExactMatchin the operation can be used.
Mapping operation properties
| Attribute name | Data type | Description |
|---|---|---|
| type | string | Refers to the type of operation to perform. For a list of supported operation types, see Operation Types. |
| sourceProperty | string | Refers to the source schema property name where the value is obtained. |
| targetProperty | string | Refers to the target schema property name to which the data will be transformed. |
| value | string | Used to define a value. |
| andCondition | array of AndCondition schema | Used to define conditions when complex operations are bundled together. For more information, see the AndConditions schema properties table. |
| attributes | array of Attributes schema | Refers to the Attributes used to specify how and from where the value will be taken. For more information, see the Attributes schema properties table. |
| priority | integer | Refers to operations like "CONDITIONAL_PRIORITY" which are containers and can be evaluated like an if else block. The "CONDITIONAL_PRIORITY" operation uses the 'priority' attribute to define the order of execution. An operation with priority=1 is computed first. If it succeeds, then the operations with a lower priority are not computed. |
| operator | string | Refers to the property used to specify how to concatenate multiple values. If operator="-", the concatenated value will be "concatenated-value". |
| arrayIndex | object of attributes | Used with the COPY operation to provide a condition that is used to evaluate an index in the array from which a value should be copied. For detailed information, see COPY operation with arrayIndex. |
| operations | array of operation | Refers to operations like AGGREGATE which are like containers and contain a bundle of other operations which are evaluated together to maintain the sanctity of the logical entity. |
AndCondition schema properties
Used to define conditions when complex operations which are bundled together under AGGREGATE to define a logical construct.| Attribute N\name | Data type | Required | Description |
|---|---|---|---|
| type | String | required | This denotes the type of conditions. For list of supported condition types see Operation Conditions |
| attributes | array of attributes | required | This is the list of attributes on which the conditions hold. |
Example of AndCondition schema:
{
"type": "CONSTANT",
"value": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:ELEV:",
"targetProperty": "data.VerticalMeasurements[#].VerticalMeasurementPathID",
"andCondition": [
{
"type": "ifAllExists",
"attributes": [
{
"sourceProperty": "data.elevationReference.name"
},
{
"sourceProperty": "data.elevationReference.elevationFromMsl.value"
},
{
"sourceProperty": "data.elevationReference.elevationFromMsl.unitKey"
}
]
}
]
}Attributes schema properties
`Attributes` are used to specify how and from where the value will be taken. They are used in the `AndConditions` schema or with the `CONCATENATE` operation.| Attribute name | Data type | Required | Description |
|---|---|---|---|
| sourceProperty | string | optional | Denotes the source property for which the condition holds good. |
| targetProperty | string | optional | Denotes the target property for which the condition holds good. |
| value | string | Required when used in the andCondition schema and is of type "equals" or in the arrayIndex schema. | This denotes the value of the attribute or indicates the attribute name for which the value needs to be looked up. |
Example of Attributes schema in the CONCATENATE operation:
{
"mappings": [
{
"identifier": "data.WellboreId",
"operations": [
{
"type": "CONCATENATE",
"operator": "-",
"attributes": [
{
"sourceProperty": "data.UWI"
},
{
"sourceProperty": "data.UBHI"
}
],
"targetProperty": "data.WellboreId"
}
]
}
]
}Example of Attributes schema in andCondition and is of type "equals":
{
"mappings": [
{
"type": "CONDITIONAL_PRIORITY",
"operations": [
{
"type": "COPY",
"sourcProperty": "data.name",
"targetProperty": "data.VerticalMeasurements[#].VerticalCRSID",
"priority": 1,
"andCondition": [
{
"type": "equals",
"attributes": [
{
"sourceProperty": "data.name",
"value": "KB"
}
]
}
]
},
{
"type": "CONSTANT",
"value": "Test Value",
"targetProperty": "data.VerticalMeasurements[#].VerticalCRSID",
"priority": 2
}
]
}
]
}Example of Attributes schema in arrayIndex:
{
"mappings": [
{
"type": "COPY",
"targetProperty": "data.VerticalMeasurements[#].VerticalReferenceID",
"value": "@targetProperty:data.VerticalMeasurements[?].VerticalMeasurementID",
"arrayIndex": {
"targetProperty": "data.VerticalMeasurements[?].VerticalCRSID",
"value": "partition-id:reference-data--CoordinateReferenceSystem:VerticalCRS::EPSG::5714:"
}
}
]
}The Mapping service supports the following operations using different endpoints.
###A) Create mapping definition
You can create a mapping definition using the POST /mappings endpoint as listed in the API Reference
{
"mappingIdentity": {
"authority": "`<authority>`",
"sourceSchema": {
"authority": "`<authority>`",
"source": "petrel",
"entityType": "wellbore",
"schemaVersionMajor": 1
},
"targetSchema": {
"authority": "`<authority>`",
"source": "wks",
"entityType": "wellbore",
"schemaVersionMajor": 1
}
},
"mappings": [
{
"identifier": "locationWGS84",
"operations": [
{
"type": "COPY_SUBSTRUCTURE",
"sourceProperty": "data.locationWGS84",
"targetProperty": "data.locationWGS84"
}
]
},
{
"identifier": "dlLatLongWGS84",
"operations": [
{
"type": "COPY",
"sourceProperty": "data.wellHeadWgs84.latitude",
"targetProperty": "data.dlLatLongWGS84.latitude"
},
{
"type": "COPY",
"sourceProperty": "data.wellHeadWgs84.longitude",
"targetProperty": "data.dlLatLongWGS84.longitude"
}
]
},
{
"identifier": "WellandDefinitiveTrajectory",
"operations": [
{
"type": "RELATIONSHIP",
"sourceProperty": "data.WellID",
"targetProperty": "data.WellID"
},
{
"type": "RELATIONSHIP",
"sourceProperty": "data.TrajectoryTypeID",
"targetProperty": "data.TrajectoryTypeID"
}
]
},
{
"identifier": "NameAliases",
"operations": [
{
"type": "COPY",
"sourceProperty": "data.NameAliases[1]",
"targetProperty": "data.NameAliases[0]"
}
]
},
{
"identifier": "ResourceHostRegionIDs",
"operations": [
{
"type": "RELATIONSHIP_ARRAY",
"sourceProperty": "data.ResourceHostRegionIDs[*]",
"targetProperty": "data.ResourceHostRegionIDs[*]"
}
]
}
]
}{
"id": "`<authority>`:mapping:71e2198321093812w812e9",
"version": "4567891234",
"mappingIdentity": {
"authority": "`<authority>`",
"sourceSchema": {
"authority": "`<authority>`",
"source": "petrel",
"entityType": "wellbore",
"schemaVersionMajor": 1
},
"targetSchema": {
"authority": "`<authority>`",
"source": "wks",
"entityType": "wellbore",
"schemaVersionMajor": 1
}
},
"createdBy": "user@abc.com",
"dateCreated": 2018-03-20T09:12:28Z,
"scope": "INTERNAL",
"kind": "`<authority>`:mapping:mapping:1.0.0",
"mappingSchemaVersionMajor": 1,
"mappingSchemaVersionMinor": 0,
"mappingSchemaVersionPatch": 0
}###B) Get all created mapping definitions
You can get all the created mappings for a specific data partition using the GET /mappings endpoint based on the following parameters:
| Attribute | Use | Example | Datatype | Required (Yes/No) |
|---|---|---|---|---|
| scope | Defines the scope of the created mapping definitions. Possible value: INTERNAL The current implementation only supports getting the INTERNAL mapping definition. | INTERNAL | string | Yes |
| limit | Limits the count of the mapping definitions being fetched. | 20 | number | No. If not given, then 50 is the default limit value. |
| offset | Skips the first few numbers of the mapping definitions while getting it. For example, if any data partition has 100 INTERNAL mapping definitions, and you want to view only the last 30 mapping definitions, then you can set offset the value to 70. | 50 | number | No. If not given, then 0(zero) is the default offset value. |
| sourceSchemaKind | Gets the mapping definitions of a specific source. | osdu:petrel:wellbore:2.0.0 | string | No. If not given, then all mapping definitions present for the specific data-partition are returned in response irrespective of the sourceSchemaKind. |
###C) Get a specific mapping definition by ID
You can get a specific mapping definition using the GET /mappings/{id} endpoint based on the ID of the created mapping definition.
Example mapping definition ID: "slb-osdu-prod-des-prod-testing:mapping:5384f51d-26df-41e4-a46f-955893628cdd".
Response of a Get specific mapping definition API
{ "mappingInfo": { "id": "<authority>:mapping:71e2198321093812w812e9", "version": 1621788286530, "mappingIdentity": { "authority": "<authority>", "sourceSchema": { "authority": "<authority>", "source": "petrel", "entityType": "wellbore", "schemaVersionMajor": 1 }, "targetSchema": { "authority": "<authority>", "source": "wks", "entityType": "wellbore", "schemaVersionMajor": 1 } }, "createdBy": "user@abc.com", "dateCreated": "2018-03-20T09:12:28Z", "scope": "INTERNAL", "kind": "<authority>:mapping:mapping:1.0.0", "mappingSchemaMajorVersion": 1, "mappingSchemaMinorVersion": 0, "mappingSchemaPatchVersion": 0, "filelocation": "osdu-wks-mappings", "fileName": "<authority>:mapping:71e2198321093812w812e9:1621788286530.json", }, "mappings": [ { "identifier": "locationWGS84", "operations": [ { "type": "COPY_SUBSTRUCTURE", "sourceProperty": "data.locationWGS84", "targetProperty": "data.locationWGS84" } ] }, { "identifier": "dlLatLongWGS84", "operations": [ { "type": "COPY", "sourceProperty": "data.wellHeadWgs84.latitude", "targetProperty": "data.dlLatLongWGS84.latitude" }, { "type": "COPY", "sourceProperty": "data.wellHeadWgs84.longitude", "targetProperty": "data.dlLatLongWGS84.longitude" } ] }, { "identifier": "WellandDefinitiveTrajectory", "operations": [ { "type": "RELATIONSHIP", "sourceProperty": "data.WellID", "targetProperty": "data.WellID" }, { "type": "RELATIONSHIP", "sourceProperty": "data.TrajectoryTypeID", "targetProperty": "data.TrajectoryTypeID" } ] }, { "identifier": "NameAliases", "operations": [ { "type": "COPY", "sourceProperty": "data.NameAliases[1]", "targetProperty": "data.NameAliases[0]" } ] }, { "identifier": "ResourceHostRegionIDs", "operations": [ { "type": "RELATIONSHIP_ARRAY", "sourceProperty": "data.ResourceHostRegionIDs[]", "targetProperty": "data.ResourceHostRegionIDs[]" } ] } ] }
The response contains the "filelocation" and "fileName" attributes, which tell you the loacation of the mapping file. The WKS service uses this actual mapping file to identify the source and target attributes and the mapping operations between them.
###D) Update a specific mapping definition You can update a specific mapping definition using the PUT /mappings/{id} API by using the ID of the created mapping definition and the requested body as shown in the following example.
Sample request to update a mapping definition
[ { "identifier": "locationWGS84", "operations": [ { "type": "COPY_SUBSTRUCTURE", "sourceProperty": "data.locationWGS84", "targetProperty": "data.locationWGS84" } ] }, { "identifier": "dlLatLongWGS84", "operations": [ { "type": "COPY", "sourceProperty": "data.wellHeadWgs84.latitude", "targetProperty": "data.latitude" }, { "type": "COPY", "sourceProperty": "data.wellHeadWgs84.longitude", "targetProperty": "data.longitude" } ] }, { "identifier": "TrajectoryType", "operations": [ { "type": "RELATIONSHIP", "sourceProperty": "data.TrajectoryTypeID", "targetProperty": "data.TrajectoryTypeID" } ] }, { "identifier": "NameAliases", "operations": [ { "type": "COPY", "sourceProperty": "data.NameAliases[1]", "targetProperty": "data.NameAliases[0]" } ] }, { "identifier": "ResourceHostRegionIDs", "operations": [ { "type": "RELATIONSHIP_ARRAY", "sourceProperty": "data.ResourceHostRegionIDs[]", "targetProperty": "data.ResourceHostRegionIDs[]" }, { "type": "RELATIONSHIP_ARRAY", "sourceProperty": "data.tieInWellbore.ids[]", "targetProperty": "data.ResourceHostRegionIDs[]" } ] } ]
Note: In an update operation, the identifiers and attributes that are present in the mapping[] parameter of the created mapping definition file are replaced with those that are listed in the request body.
Here, the update operation generates a new version of the same mapping ID, and when you try to get the mapping, the mapping definition ID with latest version is returned in response.
###E) Delete a specific mapping definition You can delete a mapping definition using the DELETE/mappings/{id} endpoint as listed in the API Reference. You must be a member of users.datalake.admins.
Example mapping definition ID: "slb-osdu-prod-des-prod-testing:mapping:5384f51d-26df-41e4-a46f-955893628cdd".
The Mapping service requires that users have dedicated roles in order to use it. Users must be a member of users.datalake.editors, users.datalake.admins, or users.datalake.ops.
In addition to service roles, users must be a member of users.datalake.viewers to access the data.
To delete the mapping, users must be a member of users.datalake.admins.
While sending a request to the Mapping service, you need 2 mandatory http request headers.
The slb-partition-id enables read and write operations to the appropriate data partition.
Example:
slb-partition-id: `<authority>`All APIs require an authenticated user token in the authorization header of the HTTP call.
Example:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzIOFDJSosdfjsdoifjSDFOSDSDFAll available Mapping service APIs are listed in the API Reference.