Event sharing between two EarthRanger sites.

Quickly find what you need by using the table of contents in the right sidebar. It directs you to key sections like prerequisites, scope, and configuration.

Prerequisites

Source Site

• Permissions. Create a user with permissions to read the event categories that will be shared with the destination.
• Authentication Token. Create a session token for this user. 

Destination Site

• Permissions. Create a user with the “Gundi Service Account” permission set to allow the integration to create the necessary event categories and event types.
• Authentication Token. Create a session token for this user.
• Event Categories and Event Types. Although you can let the integration create the necessary event categories and event types, you may also choose to create them manually. 
  If you choose to create these manually, please read the section “Destination Event Schema” within the “Additional Technical Documentation” section in this article, and configure update_schema to false in Gundi.  

Scope Specifications

Event Types
Before synchronizing any events, all event types are first synced from the Source system to the Destination system.

The Destination event types retain the schema of the Source event types, except that enumeration and query fields are replaced with strings, and a few additional properties are added.

The “value” of the Destination event type is set to the value of the Source event type, prepended with the configured source_system_value. The display name of the Destination event type is set to the display name of the Source event type, prepended with the configured source_system_name.

For example, if the display name of the Source system is "Site A", then a "Snare" event type from the Source system would become "Site A - Snare" in the Destination system.

Event Categories
Each Source event category is also created or updated in the Destination system. For example, a "Security" event category in the Source system would become "Site A - Security" in the Destination system.

Events
Active and resolved events from the Source system that have been updated within the past x days (days_to_sync) will be created or updated in the Destination system.

Also included:

• Attachments.
• Notes.

Not transferred:

• The update history of the Source event
• The "Reported By" field of the Source event

Incidents
If a set of reports is grouped as an incident in the Source system, it will also be grouped as an incident in the Destination system.

Manual Event Schema Updates (Optional)

The schema for the event types on the destination site need to contain a few fields, which are created automatically when update_schema is set to True in Gundi. Skip this section if you will configure Gundi to update the schema automatically.  

When update_schema is set to False, these fields need to be added manually. These properties need to be added to the Properties section, but not on the Definition section. 

   "er2er_src_id":{
      "type":"string",
      "title":"Event Type Serial Number from Source ER System"
   },
   "er2er_src_system":{
      "type":"string",
      "title":"Name of Source ER System"
   },
   "er2er_src_serial_number":{
      "type":"string",
      "title":"Serial Number of Source Event"
   },
   "er2er_src_service_root":{
      "type":"string",
      "title":"Service Root of Source Event"
   }

Configuring Gundi v1

Go to Gundi v1.

Go to the Inbound Integrations and select Add Integration.

Follow the steps below to configure the integration:

Follow these steps to complete the form:

Name: Provide an appropriate name for this connection (e.g., ER Site 1 to ER Site 2)

Organization: Select the relevant organization.

Type: Choose “ER2ER”.

Endpoint: API endpoint of the source ER system.

Token:  Token for the user session token on the source ER system.

State:  

{
   "days_to_sync":{{numeric_value}},
   "delete_unmatched_events":{{true_or_false}},
   "dest_endpoint":"{{er_site}}/api/v1.0",
   "dest_token":"{{text}}",
   "prepend_system_to_categories":{{true_or_false}},
   "prepend_system_to_event_types":{{true_or_false}},
   "prepend_system_to_event_titles":{{true_or_false}},
   "source_system_name":"{{text}}",
   "source_system_value":"{{text}}",
   "update_schema":{{true_or_false}},
   "within_featuregroups":[
      "{{text}}"
   ]
}

days_to_sync - How far back the synchronization looks for changes in the Source system to a maximum of 30 days.

dest_endpoint - The API endpoint of the Destination system

dest_token - The user session token for Destination system

source_system_name - User-friendly name used to identify the events from the Source system when looking at the Destination system

source_system_value - A value that is prepended to the unique identifiers of any event types or categories that are created so as to identify the association with the Source system.

update_schema - When the value is set to true, the event_type will be created on the destination side. It will use the same event category that it came from on the source side. Consult “Support Notes - Manual Event Schema Updates” in this article for more information.

Example:

{
   "days_to_sync":10,
   "delete_unmatched_events":false,
   "dest_endpoint":"https://sandbox.pamdas.org/api/v1.0",
   "dest_token":"0Kfl3LOh0bIgKwcYVoGVWknLMxjh6h",
   "prepend_system_to_categories":true,
   "prepend_system_to_event_types":true,
   "prepend_system_to_event_titles":true,
   "source_system_name":"VCC",
   "source_system_value":"vcc",
   "update_schema":true,
   "within_featuregroups":[
      "2b2b7728-c215-434c-bf01-a9796d5e9a7b"
   ]
}

Click Save.

Adjusting Permissions

Once the event categories and event types have been created on the destination site, you may remove the “Gundi Service Account” permission from the user created on the destination site for this integration. 

When you remove the Gundi Service Account permission set to the user:

• Grant the user the necessary permissions to the event categories created by this integration. 
• If update_schema was set to True in Gundi, grant the user the necessary permissions to read, add, update, and delete event types.

Legacy Documentation

https://allenai.atlassian.net/wiki/spaces/ER/pages/20737884222/ER2ER+Events 

 Coming soon.