Imports

Imports in DryMerge allow for the inclusion of pre-defined entities with the ability to modify or alias their attributes. The import mechanism enables DryMerge configurations to be more modular and reusable.

Anatomy of an Import

An import object comprises several key fields:

  • id: A unique identifier for the import.
  • use: A list of entities to import.

Anatomy of a Use statement

  • id: The ID of the entity to import.
  • as: (Optional) An alias for the imported entity. If not provided, the entity will be imported with its original ID.
  • but: (Optional) Modifications of the JSON to apply to the imported entities.
  • hydrate: (Optional) Values to fill into templates when importing them.
  • replace (Optional) A string to string mapping of raw strings to replace in the imported entities.

Example 1: Importing a Gmail Trigger Template

In this example, a Gmail trigger template is imported and hydrated with specific values.

organization: DryMerge
version: 1
infra:
  our_trigger.import:
    use:
      # Note how we're using a template id and hydrating it with specific values
      - id: customer-gmail-trigger.template
        hydrate:
          user_id: 'edward'
          refresh_token: 'MY_REFRESH_TOKEN'
          message: 'Edward received a new email!! Huge for us!'

Example 2: Importing and Modifying an Existing API Node

In this example, we import an existing API node called entrypoint.api and modify its behavior by adding a sleep operation.

Initial node:

  entrypoint.api:
    request:
      url: https://httpstat.us/200
      method: GET
    dependencies:
      xd:
        id: trigger-initial.api

Modified using an import:

organization: DryMerge
version: 1
nodes:
  new_entrypoint.import:
    use:
      - id: entrypoint.api
        as: modified_entrypoint.api
        but:
          <modified_entrypoint.api>.request.url: https://httpstat.us/200?sleep=5000  # Add a sleep of 5 seconds before the request

In the modified version, we’ve imported the entrypoint.api node as modified_entrypoint.api and added a sleep of 5 seconds before the request is executed.

Templates

Templates in DryMerge provide a reusable blueprint for defining entities. They allow for the specification of placeholders, which can be filled in at a later time, either during import or when calling a specific API. This ensures that repetitive configurations can be abstracted away into templates, allowing for more modular and maintainable DryMerge code.

Anatomy of a Template

In DryMerge, a Template serves as a blueprint for defining entities with placeholders. These placeholders can be filled in at a later time, either during import or when calling a specific API endpoint, enabling a dynamic and flexible configuration.

Here’s a breakdown of the primary components within a template:

  • id: A unique identifier for the template. This typically follows the pattern [organization]/[namespace]/[name].[type]:[version].

  • content: The main body of the template, containing the entities and configurations it represents. This section can have placeholders, denoted by {{template.placeholder_name}}, which are expected to be provided values when the template is used.

  • schemas: (Optional) This section can be used to define JSON schemas that validate the structure and content of provided data when the template is instantiated.

  • defaults: (Optional) This section can be used to define default values for the template’s placeholders.

  • perms: (Optional) Permissions related to the node.

  • metadata: (Optional) Additional metadata related to the entity.

For instance, in our earlier Gmail monitoring example:

Here’s an example of a template:

organization: DryMerge
version: 1
templates:
  # This template lays out all the entities needed to monitor a specific user's Gmail account and trigger an action when they receive a new email.
  customer-gmail-trigger.template:
    content:
      # This is the trigger for a specific user's Gmail account
      google/new-gmail-{{template.user_id}}.trigger:
        running: true
        check:
          hit:
            id: google/emails-{{template.user_id}}.api
          schedule: '{{template.schedule}}'
        conditions:
          if-new-email-received:
            - field: 'messages'
              diff:
                query: 'length(@) > `0`'
        then:
          hit:
            id: google/action-{{template.user_id}}.api
            with:
              message: '{{template.user_id}} received a new email!!'
  defaults:
    schedule: '1/5 * * * * *'

The placeholder {{template.user_id}} in the content section denotes a variable part of the configuration, which is expected to be provided a specific value when the template is instantiated. This allows the same template to be reused for monitoring different Gmail users by simply providing different user_id values during instantiation. We provide defaults for the schedule placeholder in the defaults section, which can be overridden when the template is instantiated. If schedule is not provided, it will hydrate as 1/5 * * * * *.