Introduction
OpsRamp provides you the capability to build your integration using Custom Integration framework.
Custom integration is configured between OpsRamp and your application if any third-party or other in-house applications are not present in the available integrations list.
Note
Alerts or tickets are integrated from any third-party application that supports REST APIs.Using Custom integration, multiple tenants can inherit properties of a parent integration automatically without using respective configuration. For more details, view Custom integration for multiple tenants with inherited details.
Configure Custom Integration
Custom integration provides multiple options to set up the desired integration.
| Integration Type | Description | Associated Role | Configuration Type | Inbound Authentication |
|---|---|---|---|---|
| Custom | Default integration category. Custom is used when your desired integration is not available in the list of OpsRamp available integrations. | Multiple roles | Bidirectional | OAUTH2 |
| Collaboration | Collaboration displays the Direction field where you need to specify the direction of collaboration integration. Available options are Inbound-Outbound, Inbound, and Outbound. If a direction is not specified, then Inbound-Outbound is selected as the default direction. | Default role | Bidirectional | OAUTH2, Webhook |
| Monitoring | Selecting Monitoring displays the Alert Source field where you need to specify the alert source from the Alert Source drop-down list. If an alert source is not selected, then Custom is selected as the default alert source. | Default role | Inbound | OAUTH2, Webhook |
| Process Automation | Select to create an integration for custom automation | NA | Outbound | NA |
| SSO | Select to create a custom integration for the unique client. You can install and integrate only one instance of SSO installation. If an SSO integration is already installed using the SSO tab from Available Integrations, then the SSO category is not displayed in Custom Integrations. | NA | NA | NA |
Before building the custom integration, identify the use case, and do the required configurations.
Preparing custom integration using OpsRamp involves:
- Installing custom integration
- Configuring custom integration
The scenarios below describe custom integration with an example for bidirectional, inbound or outbound, and SSO.
Scenario-1: Bidirectional Integration
Bidirectional integration includes both Inbound (third-party application to OpsRamp) and Outbound (OpsRamp to third-party application) communication.
Applicable to: Custom and Collaboration
Note
This collaboration integration supports the webhook-based inbound calls with different types of service management requests. For example, you can select one or multiple Entity Types from Incident, Service Request, Problem, and Change.Step 1: Install the custom integration
To install:
- From All Clients, select a client.
- Go to Setup > Integrations > Integrations.
- From Available Integrations, select Other > Custom Integration.
- Enter the following details and click Install:
- Name
- Description
- Category: Select Custom or Collaboration from the drop-down option.
- Upload Logo
Step 2: Configure the custom integration
The custom integration category allows for bidirectional communication. Bidirectional integration includes both inbound (third-party application to OpsRamp)) and outbound (OpsRamp to Third-party application) communication.
To configure inbound-outbound communication, provide the following:
For Inbound:
- Authentication Type: OpsRamp supports APIs with OAUTH2 for Custom.
- Role: Select the role of the user installing the integration.
Note: You can execute only those APIs that are associated with the selected role. - Click Save and make a note of the Tenant Id, Key, and Secret or Token and Webhook URL depending upon the authentication type selected.
- Map Attributes: Map the tenant entity attributes with OpsRamp entity if any.
- Field mapping: Maps the fields from your application entity attributes to OpsRamp entity attributes.
Example: If you are trying to integrate events as OpsRamp alerts, then alert subject, alert description, alert time, alert resource, and hostname are field mapping attributes. - Field value mappings: If an attribute has multiple values to map, then that attribute falls under field value mappings.
Example: If you are trying to integrate events as OpsRamp alerts, then alert state (with values critical, warning, Info) and alert metric are field value mapping attributes.
Notes:- For Webhook authentication type, map attributes only if your application supports Webhooks with JSON format.
- Mapping attributes is NOT required if your application is capable of calling OpsRamp APIs with OAuth2 authentication.
- Field mapping: Maps the fields from your application entity attributes to OpsRamp entity attributes.
- ITSM Properties: Define properties required to call Custom APIs using events.
For Outbound:
Outbound configurations capture all details required to call third-party application APIs from OpsRamp.- Integration Basic Authentication Configuration: Configure basic notification details to trigger the integration events defined. Provide third-party application details, such as REST API URL and authentication details. This step is not mandatory. You can also configure notification details as part of defining integration events.
For JWT, select REST API as Notification Type and JWT as Authentication Type. Provide the JWT authentication for Username and Password based on the third-party applications. You can also provide the attributes in any of the following:- Headers
- Payload
- Query parameter in URI
- Map Attributes: Maps the tenant entity attributes with the OpsRamp entity if any. This mapping is not mandatory, you can also map attributes as part of defining integration events. This is similar to Inbound mapping attributes. In outbound, OpsRamp converts the mapping attributes data before sending it to the third-party application.
Only one mapping attribute is required.
Field value mappings: If an attribute has multiple values to map, then that attribute falls under field value mappings.
Example: If you are trying to integrate incidents from OpsRamp to your application, then the incident status and priority are the attributes available to map values. - Integration Events: Events are used for sending certain notifications when an action is performed on OpsRamp entities. Integration event configuration carries the information of OpsRamp entities to integrated, JSON payload, headers, response parsing details. Configure the JSON payload with the placeholder tokens. Actual data is replaced dynamically at run time. Placeholders are provided on the right pane.
- Validate: Validate the integration by providing the hard-coded JSON data payload. This validation event is not audited. The response from the third-party application is displayed after validation.
- Failure notifications: Configure your email address to get notified about failures.
- Integration Basic Authentication Configuration: Configure basic notification details to trigger the integration events defined. Provide third-party application details, such as REST API URL and authentication details. This step is not mandatory. You can also configure notification details as part of defining integration events.
Monitoring of Integrations
Select templates from Monitoring of Integrations if you want to monitor integration failures. See monitoring integration failures for more information.Audit Logs
View logs from the Audit Logs tab.
Note: Logs are visible only after successful API calls.
See Freshservice Integration for more information.
Scenario-2: Capturing the data into OpsRamp (Inbound to OpsRamp)
In this scenario, data is captured inbound to OpsRamp.
Inbound configurations capture all the details required to call OpsRamp APIs in a third-party application.
Capturing or consuming data into OpsRamp includes only inbound communication.
Applicable to: Collaboration and Monitoring
Note
This collaboration integration supports the webhook-based inbound calls with different types of service management requests. For example, you can select one or multiple Entity Types from Incident, Service Request, Problem, and Change.To configure inbound communication, follow the steps mentioned for inbound under the Bidirectional scenario.
See Webhook integration using a custom framework for more information.
Scenario-3: Sending the data from OpsRamp (Outbound from OpsRamp)
Outbound configurations capture all details required to call third-party application APIs from OpsRamp.
Applicable to: Collaboration
To configure outbound communication, follow the steps mentioned for outbound under the Bidirectional scenario.
Scenario-4: Sending data from OpsRamp (Outbound from OpsRamp) for Automation
Outbound configurations to send data from OpsRamp and used as workflow entities for automation. See Automation Integration for details.
Scenario-5: Third-party Authentication (SSO)
SSO integration allows to specify custom third-party SSO integrations.
To configure SSO integration, provide the following:
- Issuer URL: Identity provider Issuer URL
- Redirection URL: SAML EndPoints for HTTP
- Logout URL: URL for logging out
- Certificate: x.509 Certificate
Once installed, verify the configuration information (properties and user provision).