Snap-in custom schema fragments

A snap-in can declare custom schema fragments in its version 2 manifest. Use a fragment to add app-specific fields to an existing DevRev object type or to define a new custom object type. Declare each fragment under the top-level custom_schema_fragments list.

Define a custom object type

This example defines an asset custom object type and gives the snap-in's service account permission to create and update its records:

version: "2"
name: Asset tracker
description: Track assets in DevRev.

service_account:
  display_name: Asset tracker
  scopes:
    self:
      - scope: custom_object:asset:write
        optional: false
        reason: Create and update asset records.

custom_schema_fragments:
  - leaf_type: asset
    id_prefix: AST
    body:
      leaf_type: asset
      type: app_fragment
      is_custom_leaf_type: true
      description: Fields for tracked assets.
      app_display_name: Asset tracker
      fields:
        - name: serial_number
          field_type: text
          description: The asset's serial number.
          ui:
            display_name: Serial number

Set is_custom_leaf_type: true to define a new object type. The manifest's leaf_type and body.leaf_type must match. Supply id_prefix on the fragment entry for a new custom object type; it is used for the object's display IDs. When the manifest is applied, the snap-in creates the custom object type if it does not already exist, then adds the fields from its app fragment. You can then create and manage records of that leaf_type with the custom objects APIs. To set fields from the app fragment, select that fragment in custom_schema_spec as described in object customization.

Add fields to an existing object type

Set is_custom_leaf_type: false to add app-specific fields to an existing type, such as ticket. This does not define a new custom object type:

custom_schema_fragments:
  - leaf_type: ticket
    body:
      leaf_type: ticket
      type: app_fragment
      is_custom_leaf_type: false
      description: Ticket fields used by this snap-in.
      fields:
        - name: external_reference
          field_type: text
          description: ID of the corresponding external record.
          ui:
            display_name: External reference

Each manifest entry has a leaf_type and a body using the schema fragment format. Manifest-defined fragments must use type: app_fragment; do not use a tenant_fragment or custom_type_fragment as the body.type. The snap-in supplies the app association and calculates removed fields during updates, so do not set body.app or body.deleted_fields yourself. Use distinct leaf_type values for separate entries. The fields list describes the app-specific fields added to that object type; see object customization for field descriptors and how fragments contribute to an object's schema.

Grant the right permissions

Declaring a fragment defines a schema; it does not grant the snap-in's service account permission to read or change records of the new custom object type. Add the appropriate scope under service_account.scopes.self for each custom leaf_type the snap-in accesses:

• custom_object:<leaf_type>:read to read its records.
• custom_object:<leaf_type>:write to create or update its records.
• custom_object:<leaf_type>:all to delete its records as well.

For example, the asset fragment above uses custom_object:asset:write. Choose only the permission your snap-in needs. These object permissions are distinct from permissions to change a schema fragment. Manifest-defined fragments are applied by the snap-in platform; if your snap-in's own code also calls schemas.custom.set to create or update fragments, its service account needs custom_type_fragment:write for that API, regardless of whether the request body is an app, tenant, or custom-type fragment.