Guide for Configuring the External Service Incident Custom on the Elven Platform

The External Service Incident Custom feature allows you to connect your API to the Elven Platform in a practical and efficient way. With this functionality, your API can send data directly to the platform using a URL specifically generated for this purpose. This data can be used to open custom incidents, allowing you to monitor events or critical situations in an automated manner. It’s a simple way to integrate your system with the platform, ensuring a quick response aligned with your needs.

In addition, you can also send status updates, such as issue resolution. This means that as soon as an incident is handled in your API, the status can be automatically updated in the Elven Platform to Resolved. This integration reduces manual effort and improves visibility into the workflow, providing more control and peace of mind in managing your services. With this flexibility, the External Service Incident Custom adapts perfectly to your environment, putting you in control of your operations.

Accessing External Service Incident Custom

• Navigate to the main menu and click on Services Hub.

• In External Services Monitoring, select the item Incident Custom.

Configuring API Token

To configure the External Service Incident Custom, it is necessary to generate an API Token. This token will be included directly in the URL as part of the authentication, serving as an essential security item to ensure that only authorized users can access and interact with the external service.

• In the top menu, under your user settings, click on Organization Settings.

• In the API tab, click the + button to create a new API Token.

External Service Incident Custom configuration

The configuration of the fields in External Service Incident Custom is an essential step to ensure that your incident notifications work efficiently and reach the right people at the right time. The first field, External Service Name, is where you should assign a name to the service being integrated. This name will appear in dashboards and reports, making it easier to quickly identify the service among others. Choose a clear and descriptive name, as it will be your reference for managing and reviewing the incident history in the future.

The Responders field is the bridge between the incident and the problem resolution. Here, you define who will be notified when the incident is triggered—whether specific individuals, entire teams, or even automated systems. This field is vital to ensure that incident notifications reach the right people, avoiding delays and confusion. Add relevant contacts, such as emails or team IDs, and make sure all responsible parties have the necessary information and access to act quickly. With this configuration, you turn incidents into immediate and effective actions, ensuring a smooth and reliable experience for everyone involved.

External Service Incident Custom URL

When configuring an External Service Incident Custom, one of the most important steps is selecting the API Token you previously generated. This key acts as a unique credential that securely connects your system to the incident notification service. Think of it as a “master key” that enables authentication and communication between platforms. Make sure to choose the correct API Token and keep it protected, as it is essential for the service to function and to ensure the integrity of the integration.

After selecting the API Token, you will gain access to the External Service Incident Custom URL, which is generated automatically. This URL will be used to send incident notifications to Elven Platform. It’s important to store this URL carefully and share it only with authorized people or systems. With this configuration, you ensure that incidents are delivered efficiently, creating a reliable experience for the teams involved and reducing potential disruptions or communication failures.

Additionally, when configuring an incident in External Service Incident Custom, it’s important to correctly fill in some key fields to ensure the system works effectively. The action field must be filled with the values “alarmed” (to open an incident) or “resolved” (to indicate the incident has been resolved). The external_aggregate_key field acts as a unique identifier for the incident and is required for both actions, as it links the opening and resolution information. Furthermore, the severity field defines the incident’s criticality and must be filled with one of the available options: critical, high, moderate, low, or informational. Also, in the tags field, you can add information that helps identify the origin of the incident. This facilitates categorization and tracking, making analysis faster and more efficient. Filling in these fields correctly helps ensure clear and effective communication between systems, allowing teams to prioritize responses based on the severity and status of the incident.

Here is an example of a CURL command for the custom integration:

curl --request POST \
--url '<Elven API URL>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: 1PcustomAuth/1.0' \
--data '{
  "title": "<incident title>",
  "description": "<incident description>",
  "external_aggregate_key": "001",
  "action": "alarmed",
  "severity": "<incident severity>",
  "tags": [
    {
      "name": "tag-00",
      "value": "value0"
    },
    {
      "name": "tag-01",
      "value": "value1"
    },
    {
      "name": "tag-02",
      "value": "value2"
    }
  ]
}' 
 

• url: API_URL generated during the creation of the External Service.

• title: Defines the title of the incident that will appear in Elven Platform.

• description: Description of the incident, which will be displayed as the “cause” in Elven Platform.

• external_aggregate_key: Identifier used to “open” and “close” the incident. It must be the same for both actions.

• action: Action performed, such as “alarmed” (to open) or “resolved” (to close) the incident.

• severity: Defines the severity of the incident (informational, low, moderate, high, critical).

• tags: Use the tags field to identify the origin of the incident and facilitate its analysis.

Once configured, the service will appear in the External Services Monitoring Center, categorized by status, making it easier to monitor incidents with priority given to those in an alarmed state.

Additional security and performance settings

• Whitelist of IPs: API communication can be configured to allow only authorized IPs. To enable or modify this setting, contact Elven Platform support.

• Rate Limiting: The default request limiting time is 5 minutes, but it can be adjusted as needed. For changes, contact Elven Platform support.

These settings ensure greater security and control over the data traffic between integrated systems.

Glossary of Technical Terms

API Token: A unique credential used to authenticate and authorize communication between your API and Elven Platform. Included in the URL generated for authentication and data submission to the external service.

External Service Incident Custom: A feature of Elven Platform that allows integration with external APIs for sending incident notifications and status updates. Automates the monitoring of critical events and enables efficient incident management.

External Service Name: The name assigned to the integrated service. Identifies the service in the platform’s dashboards and reports.

Responders: Individuals, teams, or systems responsible for responding to triggered incidents. Automatically notified to resolve incident-related issues.

External Service Incident Custom URL: Automatically generated address for sending incident notifications to the integrated service. Connects your API to Elven Platform’s incident system.

Organization Settings: Menu in Elven Platform where API tokens can be generated and managed. Location for creating new tokens for authenticating external services.

title: Title of the incident that will be displayed in Elven Platform. Provides a clear and quick view of the nature of the incident.

description: Detail of the incident, shown in the “cause” field in Elven Platform. Provides additional context for analysis and problem resolution.

external_aggregate_key: Unique identifier used to associate actions like “open” and “close” incidents. Must be the same in both actions to maintain consistency in incident management.

action: Action performed on the incident, such as “alarmed” (open) or “resolved” (close). Indicates the current status of the incident in the system.

severity: Severity level of the incident, which can be informational, low, moderate, high, or critical. Helps prioritize the response based on the incident’s severity.