Skip to content

Data types

Data type is a layer that defines how Pergamin communicates with external systems. It allows you to define the structure of the data to be exchanged and to specify rules for its validation. The data type definition is written in YAML format. The data type is required to create a data stream, which defines how documents are produced from transactions.

The data type is composed of:

name.
built from capital letters, numbers and underscores. The length of the name must not exceed 36 characters. Spaces cannot be used in the data type name.
definition.
a description of the structure in YAML format, consisting of grouped field definitions and settings. On the basis of the data type, the waidation of the data sent within the transaction is carried out.

Data Type definition

Create data type

Structure of data type and naming convention
Sample minimal data type definition in YAML format
data_type:
  header:
    type: object
    fields:
      TransactionId:
        type: string
      TransactionOwner:
        type: string

Root

The root element of the data type is the highest level element of data type. It is required and must contain the header object.

Objects

At this level of the data type, you can define objects that will be used in the data type. Object represents a group of fields which relates to specific document template. Every object must be defined as direct child elements of the data_type element.

header object is required and must contain at least two fields: TransactionId and TransactionOwner. The TransactionId field is used to identify the transaction in the external system. The TransactionOwner field is used to assign documents created within the transaction to the non-technical user existing in the organization as an author. Detailed information about the header object can be found in the Data Type Reference. Fields from the special object header will be accessible from every template assigned with this data type.

Each object must have a type attribute, which defines the type of the object. The type attribute can be of the following types:

object

defines an object that can contain other fields. The fields attribute is required for this type. Further nesting of objects is NOT possible.

Important

All fields from this object type will be accessible from templates assigned with this data type and will produce exactly one document.

Sample object definition
data_type:
  # ... 
  invoice:
    type: object
    fields:
      InvoiceValue:
        type: decimal
        required: false
      Tax:
        type: integer
        required: false
array

defines an array of objects. The items attribute is required for this type and MUST contain a definition of the object type. Further nesting of objects is NOT possible.

Important

All fields from array object type will be accessible from templates assigned with this data type and will produce that amount of documents as many objects will be sent in the transaction.

Sample array definition
data_type:
  # ... 
  invoice:
    type: array
    items:
      type: object
      fields:
        InvoiceValue:
          type: decimal
          required: false
        Tax:
          type: integer
          required: false

Fields

All fields defined in the data type must have one attribute type which is always required. Some type of fields may require additional attributes which are described in detail in the Data Type Reference.

Important

All field names must start with a capital letter and can contain only letters (camel case notation). Spaces cannot be used in the field name.

type

defines the type of the field. The type attribute can be one of following types:

  • string
  • integer
  • decimal
  • boolean
  • text
  • queue
  • email

Detailed description of the field types can be found in the Data Type Reference.

Defining queues

Data type object can contain a field of specific type queue, which is used in transactions to send a signature queue. The queue can consist of multiple steps and can be divided into two groups of participants, signers and acceptors. The structure of object has been described in detail in the Transaction Data Record Reference.

Sample queue definition for header object
data_type:
  header:
    type: object
    fields:
      TransactionId:
        type: string
      TransactionOwner:
        type: string
      Queue:
        type: queue
        required: false

Important

Definition of the queue in the data type is optional. If the queue is not defined in the data type, the document will be created in draft status and will not be sent for signature.

Sample queue definition for custom object
data_type:
  header:
    type: object
    fields:
      TransactionId:
        type: string
      TransactionOwner:
        type: string
      Queue:
          type: queue
          required: false
  invoice:
    type: array
    items:
      type: object
      fields:
        InvoiceValue:
          type: decimal
          required: false
        Tax:
          type: integer
          required: false
        Queue:
          type: queue
          required: false

Important

The queue can be defined in the data type for each object. By default, the queue should be defined in the header object and its definition affects all objects in the data type (so the queue will be applied to all documents created from transacion, especially those, which are created from custom objects). If the queue is defined in the custom object, it will be applied only to the documents created from this object.

Fields of type file

Data type object can contain a field of specific type file, which is used in transactions to send a file. This kind of field can be referenced in Data Stream template configuration to create a document from the PDF document. The structure of this field and it's required attributes has been described in detail in the Transaction Data Record Reference.

Sample file definition for header object
data_type:
  header:
    type: object
    fields:
      TransactionId:
        type: string
      TransactionOwner:
        type: string
      Queue:
        type: queue
        required: false
      File:
        type: file
        required: false

Important

The field of type file can be used in custom objects as well. That means that you can combine creating documents from the file with documents created from templates.

Concatenating fields

Sometimes it is necessary to concatenate multiple fields into one. For example, you may want to use Amount field with Currency field. In this case, you can use ref attribute to reference another field in the same object. The ref attribute can be applied only to fields of primitive types (string, integer, decimal, boolean).

Sample field concatenation
data_type:
  header:
    type: object
    fields:
      TransactionId:
        type: string
      TransactionOwner:
        type: string
      Amount:
        type: decimal
        ref: currency
      Currency:
        type: string

The Example above will produce the following value of Amount field: {value} {ref.value}.

For more information about the ref attribute, please refer to the Data Type Reference.