Submitting observations to the InfoEx via the CAAML 3.0.3 API

From InfoEx Help Information
Revision as of 19:36, 22 December 2013 by Pascal (talk | contribs) (→‎Submission of observations via CAAML 3.0.3 API)
Jump to navigation Jump to search
REQUIREMENTS
Permission Operation Administrator and higher
Connectivity Online only

This document describes how to submit observations from an external database system to the InfoEx via its CAAML 3.0.3 API. This document is aimed at IT system administrators who are setting up the exchange between the two systems on behalf of the InfoEx subscriber.

Background

To submit to the InfoEx system via the CAAML 3.0.3 API, the operator needs two pieces of information from the CAA:

  • API_KEY
    A secret token that uniquely identifies the submitting system and provides it with administration privileges for the operation.
  • OperationUUID
    The universally unique identifier of the operation used in the InfoEx system.

Please connect with the InfoEx manager at the Canadian Avalanche Association to get this information for your operation.

The CAAML 3.0.3 API is intended to make the transition of existing data systems that directly submit observations to the new InfoEx as easy as possible. By supporting the submission via the legacy CAAML 3.0.3 file format, the submission procedure of these systems only has to be adjusted minimally for the 2013/14 winter season. As a consequence, however, the InfoEx CAAML 3.0.3 API only supports observation types what were used in the legacy InfoEx system during the 2012/13 winter season. Any of the new functionalities that the new InfoEx system offers (e.g., hazard assessments, PWL tracking) is not supported by this API.

NOTE The CAAML 3.0.3 API will only be made accessible to data systems that already submitted observation directly to the legacy InfoEx system. Any new developments should be using the more advanced JSON API that is used internally by the new InfoEx system or the future CAAML 5.0 API which will both support the full functionality of the new system.

Step-by-step description

Setting up your location catalog

In the InfoEx, every observation needs to be associated with a predefined location from a location catalog. In the new InfoEx system, all locations are required to have a geospatial geometry so that they can be plotted on a Google Earth map. Since the CAAML 3.0.3 file format of the legacy InfoEx system did not support location geometries, it is not possible to submit location information to the new InfoEx system via the CAAML 3.0.3 API.

To ensure that your submissions to the InfoEx run smoothly, it is imperative that you provide the InfoEx with your complete location catalog, including the geometries of your locations, prior to submitting observations to the system.

If you have a large existing location catalog, please contact the CAA to discuss ways to efficiently integrate your catalog into the new InfoEx system.

See Location catalog overview for information on how to set up your location catalog in the InfoEx system. When you create your locations, ensure that the ExternalID property of InfoEx locations contains the location ID that you are using in your system to refer to this location. This is also the location ID you are using in your CAAML files to link your observations to this location as indicated by the XML snippet below. 

<LOCATION_REFERENCE LOC_ID="BB00000001"/>

Submission of observations via CAAML 3.0.3 API

This section described the different components of the HTTPS POST call

1. HTTPS POST URL Production server: 
{{InfoExURL|CAAML/v3}}

Training server: https://training-infoex.avalancheassociation.ca/CAAML/v3

2. HTTP HEADERS

Accept: application/json
operation: <operationUUID>
api_key: <API_KEY>

3. HTTP POST PAYLOAD (RAW XML UTF-8)

Observations in CAAML 3.0.3 format (see http://caaml.org/Schemas/V3.0.3/ for more information of CAAML 3.0.3).

4. RESPONSE (JSON)

Success: { "message": "OK" }
Error: { "message": "Error Description Here"}
If the message is anything other than "OK", then an error occurred. The message contains a description of the error.

NOTE The payload is treated as a single transaction, so in the event of an error nothing will be committed - the error in the file will need to be corrected and the entire thing re-submitted.

The most common reasons for unsuccessful submissions are:

  • The submission contains a location reference that is not known to the InfoEx system
  • The submission contains an enumeration that is not OGRS compliant (CAA Observation Guidelines and Recording Standards)

Checking your submission

Simply log into the system at https://infoex.avalancheassociation.ca/, select the 'Standard - Today' report from the reports menu and select the correct date range to check your submission.

Checking your location catalog

Since your InfoEx submission will fail if it includes a location reference that point at a location that is not known to the system, our JSON API allows you to check your existing location catalog and check whether a location exists.

To retrieve the root location of your operation (i.e., the operation area) use the following HTTPS GET call:

1. HTTPS GET URL

Production server: https://infoex.avalancheassociation.ca/

Training server: 
https://training-infoex.avalanche.ca/location?operationUUID=<OperationUUID>&type=OPERATION_AREA]]
2. HTTP HEADERS

Accept: application/json
operation: <operationUUID>
api_key: <API_KEY>

3. RESPONSE (JSON) 
[1]
  0:	
  {
    name: "AD"
    type: "OPERATION_AREA"
    abbreviation: "AD"
    externalID: "AD00000001"
    geometry: 
      {
      ...
      }
    operationUUID: "a8405755-00a9-4f99-b35e-c70f8a957ba4"
    moutainRangeUUID: "26dc02b0-e59e-42b8-b670-fac6db0c9ab1"
    uuid: "9fb259bc-89f4-4a3c-898f-01e2ebab0f21"
  }

The response contains the UUID of the root location, which can stored/used to query for the full location hierarchy of the operation. To retrieve the complete location hierarchy of your operation use the following HTTPS GET call:

1. HTTPS GET URL

Production server: <UUID of root location> https://infoex.avalancheassociation.ca//location/hierarchy/<UUID of root location>
Training server: <UUID of root location> https://training-infoex.avalancheassociation.ca//location/hierarchy/<UUID of root location>

2. HTTP HEADERS

Accept: application/json
operation: <operationUUID>
api_key: <API_KEY>

3. RESPONSE (JSON)

Same response as above, however a new element "children" will be included on any nodes that have children. Currently this returns the full geometry objects for every location, which results in significant overhead for just checking the existence of a location.

NOTE In the future, we might add a parameter that allows you to suppress the geometries, or we can create a new API call that returns back the list of id's or even a custom structure.

The externalID property of all of the location elements can now be used to proactively match the location IDs used in the location references of your submission with the avalanche locations in the InfoEx system.

If you find a location ID in your submission that does not existing in your location catalog in the InfoEx system, there are two possible solutions for resolving the issue:

  • Log into the InfoEx as an operation administrator and create the location manually. See Adding locations to the location catalog for more information about how to manually add locations to your location catalog in the InfoEx.
  • Change the location association of your observation to a location that already exists in your InfoEx location catalog. A possible approach would be to go up the hierarchy and associate the observation to the parent of the missing location.

Related documents

  • Link to relate document 1
  • Link to relate document 2

Functionality tested by

  • Dec. 22, 2013: Pascal Haegeli
Retrieved from "http://infoexhelp.avalancheassociation.ca/index.php?title=Submitting_observations_to_the_InfoEx_via_the_CAAML_3.0.3_API&oldid=1584"