Skip to main content

External Events

Refer to External Events for more information on External Events & Sources.

API Gateway​

External Events & their respective External Sources utilize routes located on aerie-gateway to perform data validation and upon success, an upload through Hasura/GQL.

Creating External Source & Event Types​

To upload schemas for External Sources and Events, users should POST to the /uploadExternalSourceEventTypes route in aerie-gateway.

The body of the request should be a JSON object with this structure:

{
  event_types: "{\"ExampleEvent\":{\"type\":\"object\" ... \}\}"
  source_types: "{\"ExampleSource\":{\"type\":\"object\" ... \}\}"
}

The values of event_types and source_types must be encoded JSON strings (not objects) containing the schemas for your External Event and Source Types (either or both). The structure of these schemas is defined on the External Event and Source Attributes page. Note that this differs from the file structure expected to be uploaded via the UI, which is a combined flat JSON structure.

Uploading a definition of a single External Source Type (ExampleSource) and a single External Event Type (ExampleEvent) should yield the following response:

{
  "createExternalEventTypes": {
    "returning": [
      {
        "name": "ExampleEvent"
      }
    ]
  },
  "createExternalSourceTypes": {
    "returning": [
      {
        "name": "ExampleSource"
      }
    ]
  }
}

Creating an External Source​

To upload External Sources, users should POST to the /uploadExternalSource route in aerie-gateway.

This endpoint expects data provided in multipart/form-data format.

When uploading through Aerie's UI, the External Source & it's contained External Events are packaged together in a single JSON file which adheres to the meta-schema defined here. A derivation_group_name can be passed in as an argument with the request which will override any value for derivation_group_name in the External Source. This argument can be ignored if there is a value for derivation_group_name in the External Source.

Note

In order to upload an External Source, the External Source Type and External Event Type must exist. For uploading types, see above.

Uploading a simple definition of an External Source with a single External Event should yield the following result:

Example Input

external_source_file

{
  "source": {
    "attributes": { "example": "Example attribute" },
    "derivation_group_name": "ExampleSource Default",
    "key": "ExampleSource:1",
    "period": {
      "end_time": "2024-008T00:00:00Z",
      "start_time": "2024-001T00:00:00Z"
    },
    "source_type_name": "ExampleSource",
    "valid_at": "2024-001T00:00:00Z"
  },
  "events": {
    [
      {
        "attributes": { "example": "Example attribute" },
        "duration": "00:00:01",
        "event_type_name": "ExampleEvent",
        "key": "ExampleEvent:1",
        "start_time": "2024-002T00:00:00Z"
      }
    ]
  }
}

Example Output

{
  "upsertDerivationGroup": {
    "name": "ExampleSource Default"
  },
  "createExternalSource": {
    "attributes": {
        "example": "Example attribute"
    },
    "derivation_group_name": "ExampleSource Default",
    "end_time": "2024-01-08T00:00:00+00:00",
    "key": "ExampleSource:1",
    "source_type_name": "ExampleSource",
    "start_time": "2024-01-01T00:00:00+00:00",
    "valid_at": "2024-01-01T00:00:00+00:00"
  }
}

GQL​

The following operations can be performed directly through GQL/Hasura and do not need to interact with Gateway like the above section.

Associating a Derivation Group to a Plan​

If a plan and a derivation group exist, they can be associated using the following GraphQL mutation:

mutation CreatePlanDerivationGroup($source: plan_derivation_group_insert_input!) {
  planExternalSourceLink: insert_plan_derivation_group_one(
    object: $source,
    on_conflict: {
      constraint: plan_derivation_group_pkey
    }
  ) {
    derivation_group_name
  }
}

This mutation requires a an argument, $source, which includes: 1) the name of the derivation group to link, and 2) the ID of the plan to link it to. See below for an example input:

{
  "source": {
    "derivation_group_name": "ExampleSource Default",
    "plan_id": 1
  }
}

This request will yield the following response:

{
  "data": {
    "planExternalSourceLink": {
      "derivation_group_name": "ExampleSource Default"
    }
  }
}

Disassociating a Derivation Group from a Plan​

To disassociate a derivation group from a plan, the following GraphQL mutation can be used:

mutation DeletePlanExternalSource($where: plan_derivation_group_bool_exp!) {
  planDerivationGroupLink: delete_plan_derivation_group(where: $where) {
    returning {
      derivation_group_name
    }
  }
}

This mutations requires an argument which is an expression returning a boolean such as:

{
  "where": {
    "_and": {
      "derivation_group_name": { "_eq": "ExampleSource Default" },
      "plan_id": { "_eq": 1}
    }
  }
}

This request will yield the following response:

{
  "data": {
    "planDerivationGroupLink": {
      "returning": [
        {
          "derivation_group_name": "ExampleSource Default"
        }
      ]
    }
  }
}

Get External Events​

query GetExternalEvents {
  external_event {
    attributes
    event_type_name
    key
    duration
    start_time
    source_key
  }
}

Get External Events from an External Source​

query GetExternalEventsFromExternalSource($sourceKey: String!, $derivationGroupName: String!) {
  external_event(where: {source_key: {_eq: $sourceKey}, derivation_group_name: {_eq: $derivationGroupName}}) {
    attributes
    event_type_name
    key
    duration
    start_time
    source_key
  }
}

Get External Sources​

query GetExternalSources {
  external_source {
    attributes
    created_at
    derivation_group_name
    end_time
    key
    owner
    start_time
    source_type_name
    valid_at
  }
}

Get External Sources from a Derivation Group​

query GetExternalSourcesFromDerivationGroup($derivationGroupName: String!) {
  external_source(where: {derivation_group_name: {_eq: $derivationGroupName}}) {
    attributes
    created_at
    derivation_group_name
    end_time
    key
    owner
    start_time
    source_type_name
    valid_at
  }
}

Get Derivation Groups​

query GetDerivationGroup {
  derivation_group {
    name
    owner
    source_type_name
  }
}