Important
Connections between EarthRanger and EarthRanger will be available through the new Gundi Portal soon. To configure your integration, kindly reach out to Gundi Support (support@projectgundi.org) for their assistance.
Event Sharing
Description
ER2ER event sharing is used to copy certain events from one EarthRanger site to another.
Prerequisites
Source
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
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.
Configurations
2. Gundi
2.1 Log in to Gundi's previous Portal
- Navigate to Gundi v1.
2.2 Verify Organization
- Confirm that an Organization exists for this connection.
2.3 Create a New Inbound Connection
- Create a connection:
- Name: Provide an appropriate name for this connection.
- 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.
Additionally, there are several variables to be defined in the State value.
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"
]
}days_to_sync - How far back the synchronization looks for changes in the Source system. If not included, a default value of 10 will be used.
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.
Next Steps
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.
Important: Assign the user the necessary permissions to write events to the categories created for this integration; otherwise, the destination user will NOT have permissions to write events.
Additional Technical Documentation
Scope Specifications
Event Types
Before synchronizing any events, the collection of all of their event types are synced from the Source to Destination system.
The Destination event types copy the schema of the Source event types, except all of the enumeration and query fields are replaced with strings, and a few additional properties are added to event types.
The “value” of the Destination event type is set to the value of the Source event type, but 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 were “Site A”, then a “Snare” event type from the Source system would become a “Site A - Snare” event type in the Destination system.
Event Categories
Each Source event category is also created or updated in the Destination system. A “Security” event category might then become a “Site A - Security” category.
Events
All of the events from the Source system that have been updated within the past x days, as specified by the days_to_sync configuration, will be created or updated in the Destination system.
For any values in the Source system’s event that were based on an enumeration or query parameter, the display value of those fields is brought over as a static string value.
Any files that were attached to the Source event are copied as attachments to the Destination event.
Notes are copied as well.
Note that two things in particular are NOT transferred: The update history of the Source event, and the “Reported By” field of the Source event.
Incidents
If a set of reports are grouped together as an incident in the Source system, then they will also be grouped as an incident in the Destination system.
Destination Event Schema
The schema for the event types on the destination site need to contain a few fields, which are created automatically when updated_schema is set to True in Gundi.
When set to False, these need to be added manually. These need to be added to the Properties section, but not on the Definition section.
These four properties are:
"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"
}Resources
| Additional information for Support | Link |
Subject Sharing
Coming soon.