Manifest

Start developing your snap-in with a manifest.yaml file. The manifest defines the snap-in’s configuration, including its name, description, version, connection details, and functionality.

Begin by setting the values for name and description in the template.

1name: Template Connector
2description: Template Connector for importing dummy data into DevRev

Set snap-in functionalities

DevRev supports creating snap-ins for importing data from an external system into DevRev (extraction) and exporting data from DevRev to an external system (loading). Implementing the extraction functionality is essential, while loading is optional.

To define the functionalities, review the functions section in the manifest.

1functions:
2  - name: extraction
3    description: Extraction function for the template snap-in
4  - name: loading
5    description: Loading function for the template snap-in
6  - name: install_initial_domain_mapping
7    description: Create blueprint and install initial domain mapping

If loading is not implemented, remove it from the list. This action also removes the option from the DevRev app.

Check the imports section next.

1imports:
2  - slug: airdrop-template-snap-in
3    display_name: Template Connector
4    description: Template Connector for importing data into DevRev
5    extractor_function: extraction
6    loader_function: loading
7    allowed_connection_types:
8      - example-connection

Update the slug, display_name, and description to match your snap-in.

If loading is not used, remove loader_function.

Ensure that extractor_function and loader_function names correspond with those in the functions section.

Establish a connection to the external system

Keyrings provide a secure way to store and manage credentials within your DevRev snap-in.

Keyrings are a collection of authentication information, used by a snap-in to authenticate to the external system in API calls. This can include a key (for example, a PAT token or API key), its type and the organization ID for which a key is valid.

This eliminates the need to expose sensitive information like passwords or access tokens directly within your code or configuration files. They also provide a valid token by abstracting OAuth token renewal from the end user, so less work is needed on the developer’s side.

Keyrings are called Connections in the DevRev app.

Configure a keyring

Keyrings are configured in the manifest.yaml by configuring a keyring_type, like in the example:

1keyring_types:
2  - id: <id of the keyring type>
3    name: <name of the keyring type>
4    description: <description of the keyring type>
5    # The kind field specifies the type of keyring.
6    kind: <"secret"/"oauth2">
7    # is_subdomain field specifies whether the keyring contains a subdomain.
8    # Enabling this field allows the keyring to get the subdomain from the user during keyring creation.
9    # Default is false.
10    is_subdomain: <true/false>
11    # Name of the external system you are importing from.
12    # This system name should start with a capital letter.
13    external_system_name: <External system name>
14    secret_config:
15      # Define the fields in the secret.
16      # Each element represents one input field.
17      # User will provide this information when creating the connection in the UI.
18      # If omitted, the user will be asked for a generic secret.
19      fields:
20        - id: <field_id>
21          name: <field_name>
22          description: <field_description>
23          is_optional: <true/false> # optional: whether the field is optional or not. Default is false.
24      # The token_verification section is used to verify the token provided by the user.
25      token_verification:
26        # The URL to which the token will be sent for verification.
27        url: <url>
28        # The HTTP method to be used for the verification request.
29        method: <method> # The HTTP method to be used for the verification request.
30        # Optional: headers to be included in the verification request.
31        headers:
32          <header_name>: <header_value>
33        # Optional: query parameters to be included in the verification request.
34        query_params:
35          <param_name>: <param_value> # optional: query parameters to be included in the verification request.
36      # The organization_data section takes care of fetching organization data and is required if is_subdomain option is false.
37      organization_data:
38        type: "config"
39        # The URL to which the request is sent to fetch organization data.
40        url: <url>
41        # The HTTP method used to send the request.
42        method: "GET"
43        headers:
44          <header_name>: <header_value>
45        # The jq filter used to extract the organization data from the response.
46        # It should provide an object with id and name, depending on what the external system returns.
47        # For example "{id: .data[0].id, name: .data[0].name }".
48        response_jq: <jq_filter>

There are some options to consider:

  • kind
    The kind option can be either “secret” or “oauth2”. The “secret” option is intended for storing various tokens, such as a PAT token. Use of OAuth2 is encouraged when possible. More information is available for secret and oauth2.

  • is_subdomain
    The is_subdomain field relates to the API endpoints being called. When the endpoints for fetching data from an external system include a slug representing the organization—such as for example https://subdomain.freshdesk.com/api/v2/tickets—set this key to “true”. In this scenario, users creating a new connection are prompted to insert the subdomain.

    If no subdomain is present in the endpoint URL, set this key to “false”. In this case, provide the organization_data part of the configuration. Specify the endpoint in the url field to fetch organization data. Users creating a new connection are prompted to select the organization from a list of options, as retrieved from the organization_data.url value.

Built with