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 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, the organization ID for which a key is valid, and in some cases the organization name.

Keyrings provide a secure way to store and manage credentials within your DevRev snap-in. This eliminates the need to expose sensitive information like passwords or access tokens directly within your code or configuration files, enhancing overall security. They also provide a valid token by abstracting OAuth token renewal from the end user.

They 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 creation.
9    # This is useful when the keyring requires a subdomain as part of the configuration.
10    # Default is false.
11    is_subdomain: <true/false>
12    # Name of the external system you are importing from.
13    # This system name should start with a capital letter.
14    external_system_name: <External system name>
15    secret_config:
16      # Define the fields in the secret.
17      # Each element represents one input field.
18      # User will provide this information when creating the connection in the UI.
19      # If omitted, the user will be asked for a generic secret.
20      fields:
21        - id: <field_id>
22          name: <field_name>
23          description: <field_description>
24          is_optional: <true/false> # optional: whether the field is optional or not. Default is false.
25      # The token_verification section is used to verify the token provided by the user.
26      token_verification:
27        # The URL to which the token will be sent for verification.
28        url: <url>
29        # The HTTP method to be used for the verification request.
30        method: <method> # The HTTP method to be used for the verification request.
31        # Optional: headers to be included in the verification request.
32        headers:
33          <header_name>: <header_value>
34        # Optional: query parameters to be included in the verification request.
35        query_params:
36          <param_name>: <param_value> # optional: query parameters to be included in the verification request.
37      # Fetching Organization Data: This allows you to retrieve additional information about the user's organization.
38      organization_data:
39        type: "config"
40        # The URL to which the request is sent to fetch organization data.
41        url: <url>
42        # The HTTP method used to send the request.
43        method: "GET"
44        headers:
45          <header_name>: <header_value>
46        # The jq filter used to extract the organization data from the response.
47        response_jq: <jq_filter>

You can find more information about keyrings and keyring types here.

Built with