Events and Events Types

EarthRanger users record and track incidents and activities within their protected areas—such as fires, wildlife sightings, snare locations etc.— which are recorded as  Events.

EarthRanger Administrators are tasked with the design and overall management of how the event forms look in the EarthRanger map UI. These event forms are called Event Types.

It’s essential to understand that Events and Event Types are essentially the same:

• Events are the incidents that users record and interact with in the EarthRanger Web and Mobile applications.
• Event Types are the data collection forms that are configured and managed by an administrator on the EarthRanger Administration website and are placed in groups called  Event Categories.
• Event Categories are groups that event types that belong to the same discipline/focus are placed in. For instance, all ecological event types, like Wildlife Sightings, Fire, and Invasive Species would fall into this “Ecology” Event Category.

Configuring Event Types

Configuring Events Types for EarthRanger users involves configuring them via the admin site. The configuration process involves the following which can be found in this article: 

• To configure a new Event, see Configuring an Event Type
• To add fields (schema) for a new Event Type, see Creating a Schema for an Event Type. 
• To hide specific Events from users, see Hiding Event Types. 

Configuring an Event Type

This section explains how to create a new Event Type. The following section, Creating a Schema for an Event Type, will guide you on adding a schema that defines the labels and fields for an Event.

Note: An Event Type must have a valid schema before it can be saved.

To configure a new Event Type:

1. Go to your EarthRanger Admin website (https://yourorganization.pamdas.org) and navigate to Home > Activity > Event Types.
2. Select Add Event Type - on the top-right of the screen. The Add Event Type page will appear.
3. In Display, enter a name for the new Event Type (e.g., "Wildlife Sightings").
4. In Value, enter a unique value, typically a text string followed by "_rep" (e.g., "wildlife_sighting_rep"). 

Note: It is good practice to enter the value string in lowercase letters and without spaces, where two or more words are used for the value, replace the space with an underscore (_) or dash (-).

5. In Category, select the appropriate category for the Event Type (e.g., Security, Monitoring, Ecology, Logistics, Maintenance etc).
   • This category determines in which group the Event Type appears. The Event Category also determines the permission set that a user should be assigned to interact with the Event Types in that Event Category.

This is because in EarthRanger the permissions are assigned at a group level. This means that for a user to have access to the events within a category, the administrator should assign them the permission related to that Event Category. For example, when an Event Category called Ecology is created the EarthRanger system will automatically create a permission set that is related to that Event Category called View Ecology Event Permissions, which will have the following standard permissions;

• Can create ecology events
• Can delete ecology events
• Can read ecology events
• Can update ecology events

Therefore, the EarthRanger site administrator would then assign this permission set to any user who should have access to all the Events in the Ecology Event Category. These users would then be able to create, read, and update all the Events recorded via the EarthRanger Web and Mobile using any of the Event Types in the Ecology Event Category. The delete standard permission will only take effect if the user has access to the administration site as deleting events can only be performed via the administration site of an EarthRanger instance.

• You can create a new category by selecting the green plus + sign.

6. Leave Is Collection unchecked.
7. Select the green plus + sign in Icon Override and choose an icon that best relates to the Event Type.

• Note: New icons cannot be uploaded via the Admin website. If a new icon is needed, contact support@earthranger.com

8. Ordernum determines the list order of the Event Type under the Event Category (Chronological sequence determines where each Event type appears - lower numbers appear first). This field can be left blank, but you can assign values, if you wish, to control the list order.
9. Set the Default Priority for the Event: Gray (default), Green, Amber, or Red.

Note: the classification of these colors are according to your preference or operational requirements. The colors are visual aids to show which events are of a certain priority; High (Red), Medium (Amber) Normal (Green), and Low (Gray)

10. Set the Default State: New (default), Active, or Resolved. 

Note: New and Active will allow all created events using this event type to appear on the events feed and on the map if they have a location associated with them. Resolved means that the events will be created but automatically not appear on the feed and map. All resolved events will have to be filtered for on the Web UI if a user wants to see them.

11. Enter a valid Schema to define the fields that will appear in the Event. 
    • For more information, refer to Creating a Schema for an Event Type.
    • If you’re not familiar with Schemas configuration, you can work with the support team with a Data Model Spreadsheet.
12. Select Save.

Creating a Schema for an Event Type

An Event Type’s schema defines the labels and text boxes (fields) that appear in the resulting Event Type form.

To create a schema in the Schema box of an Event Type, you can manually type the schema details, building it from scratch. However, it is more common to paste schema information from an existing Event Type or use a sample schema like the one shown in the Annotated sample schema for use in an Event type. You can then modify it as needed.

Pasting the annotated schema example (add image) into the Schema box of an Event Type will add fields with annotations that describe them in the resulting Event form.

Adding a Schema to an Event Type

In the section Annotated Sample Schema for Use in an Event Type, you'll find a schema that can be copied and pasted directly into the Schema box of an Event Type. This schema will generate Event forms with text boxes and labels, along with annotations that help illustrate the relationship between schema settings and the resulting Event layout.

Before proceeding to the schema, the following section, About Schemas for Event Types, provides a brief description of how schemas function within Event Types.

About Schemas for Event Types

Schemas for Event Types are written in JSON format. Each schema consists of two main sections:

• Properties: Defines the attributes of fields as stored in the database.
• Definition: Determines how the Event Type form appears to users in the EarthRanger interface.

Schema Properties

Each property in the schema must include at least a key, a type, and a title:

• key: A unique identifier for the field, used both in the database and in the definition section.
• type: Defines the data type (e.g., string, number).
• title: The text label displayed in the EarthRanger interface.

Optional properties may also include:

• minimum: Sets the minimum value for a number field (e.g., "0" for a counting field).
• maximum: Sets the maximum value for a number field (e.g., "360" for a bearing field).
• required: Sets the field to be required for completion before the event can be saved on both EarthRanger Web and Mobile applications.
• enum: Defines values that generate a dropdown list within the Event.
  • enum___xxx___values: Dropdown options from the CHOICES table.
  • query___xxx___values: Dropdown options from the SUBJECT table, defined in the DYNAMIC CHOICES table.

Schema Definitions

The definition section defines how fields appear within the EarthRanger user interface:

• key: Matches a key from the properties section and defines the order in which fields are displayed.
• htmlClass: Defines the overall display layout (currently, "col-lg-6" is used to create two columns).
• fieldHtmlClass: Affects the field's display (e.g., "date-time-picker json-schema" shows a calendar/time picker). This also determines the “size” of the fields using the "col-lg-6" = short text or "col-lg-12" = long text
• type: Fields such as "textarea" expand to two lines, allowing for text wrapping and scrolling.

Other field definitions may be supported in future updates.

Annotated Sample Schema for Use in an Event Type

Here’s an example of a schema that can be used to create an Event Type:

{
  "schema": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "DAS JSON Schema Reference List",
    "type": "object",
    "properties": {
      "string_field": {
        "type": "string",
        "title": "String Field (2 Col by using col-lg-6)"
      },
      "number_field": {
        "type": "number",
        "title": "Number Field 0<>360 (2 Col)",
        "minimum": 0,
        "maximum": 360
      },
      "time_field": {
        "type": "string",
        "title": "This is a time field. Look below in the Definition section to get date-time-picker"
      },
      "textarea_field": {
        "type": "string",
        "title": "String with text area, word wrap and scroll. 2 lines max"
      },
      "enum_field": {
        "type": "string",
        "title": "This is a drop down list populated from the Choices table where Field = yesno",
        "enum": {{enum___yesno___values}},
        "enumNames": {{enum___yesno___names}}
      },
      "query_field": {
        "type": "string",
        "title": "This is a drop down populated with Subjects defined by a query in Dynamic Choices table",
        "enum": {{query___blackRhinos___values}},
        "enumNames": {{query___blackRhinos___names}}
      },
      "multi_select_field": {
        "key": "multi_select_field"
      },
      "table_field": {
        "type": "string",
        "title": "(DEPRECATED) This is a drop down list populated from a Table",
        "enum": {{table___TrafficType___values}},
        "enumNames": {{table___TrafficType___names}}
      }
    }
  },
  "definition": [
    {
      "key": "string_field",
      "htmlClass": "col-lg-6"
    },
    {
      "key": "number_field",
      "htmlClass": "col-lg-6"
    },
    {
      "key": "time_field",
      "fieldHtmlClass": "date-time-picker json-schema",
      "readonly": false
    },
    {
      "key": "textarea_field",
      "type": "textarea"
    },
    {
      "key": "enum_field"
    },
    {
      "key": "query_field"
    },
    {
      "key": "multi_select_field",
      "type": "checkboxes",
      "title": "Multiple Selection from Choices Table - BUGS on Display and Export",
      "titleMap": {{enum___carcassrep_species___map}}
    },
    {
      "key": "table_field"
    }  ]
 
}

Hiding Event Types

Important: Do not delete Event types as it can affect your ability to retrieve existing Events. Instead, use the following steps to hide Event types that you no longer want users to access as Events Types on both EarthRanger Mobile and Web applications.

To hide an Event type:

1. At your EarthRanger Administration website (https://your_organization.pamdas.org), navigate to Activity > Event Types.
2. In the Display column on the Event Types page, select the Event type you want to hide. This will open the Event type's settings page.
3. In the Category dropdown, select HIDDEN.
   • If a HIDDEN category does not exist, follow these steps to create one:
     1. Select the green plus sign next to the Category field. The Add Event Category page will appear.
     2. Id: Leave the default unique ID unchanged.
     3. Value: Enter “hidden.”
     4. Display: Enter “HIDDEN.”
     5. Ordernum: Leave this field blank.
     6. Flag: Select System.
     7. Select Save to create the category.
4. Alternatively, you can click on the Is Active tick-box under the Default Values section of the Event Type details page. When unticked the event type will remain in its original event category but will be removed from the Event Types list.
5. Select Save on the Event type’s settings page to hide the Event type.

Once saved, the Event Type will no longer be visible to users or available in the Event Type list, but administrators will still have access to it and all the Events that were recorded using that Event Type if needed.