Props

Learn about different types of properties used in triggers / actions

Properties are used in actions and triggers to collect information from the user. They are also displayed to the user for input. Here are some commonly used properties:

Basic Properties

These properties collect basic information from the user.

Short Text

This property collects a short text input from the user.

Example:

Property.ShortText({
    displayName: 'Name',
    description: 'Enter your name',
    required: true,
    defaultValue: 'John Doe'
})

Long Text

This property collects a long text input from the user.

Example:

Property.LongText({
    displayName: 'Description',
    description: 'Enter a description',
    required: false
})

Checkbox

This property presents a checkbox for the user to select or deselect.

Example:

Property.Checkbox({
    displayName: 'Agree to Terms',
    description: 'Check this box to agree to the terms',
    required: true,
    defaultValue: false
})

Markdown

This property to show markdown snippet to the user, can be used to show documentation or instructions.

Example:

Property.MarkDown({
    value: '## This is a markdown snippet'
}),

If you want to show a webhook url to the user, use {{webhookUrl}} in the markdown snippet.

DateTime

This property collects a date and time from the user.

Example:

Property.DateTime({
    displayName: 'Date and Time',
    description: 'Select a date and time',
    required: true,
    defaultValue: '2023-06-09T12:00:00Z'
})

Number

This property collects a numeric input from the user.

Example:

Property.Number({
    displayName: 'Quantity',
    description: 'Enter a number',
    required: true
})

Static Dropdown

This property presents a dropdown menu with predefined options.

Example:

Property.StaticDropdown({
    displayName: 'Country',
    description: 'Select your country',
    required: true,
    options: {
        options: [
            {
                label: 'Option One',


                value: '1'
            },
            {
                label: 'Option Two',
                value: '2'
            }
        ]
    }
})

Static Multiple Dropdown

This property presents a dropdown menu with multiple selection options.

Example:

Property.StaticMultiSelectDropdown({
    displayName: 'Colors',
    description: 'Select one or more colors',
    required: true,
    options: {
        options: [
            {
                label: 'Red',
                value: 'red'
            },
            {
                label: 'Green',
                value: 'green'
            },
            {
                label: 'Blue',
                value: 'blue'
            }
        ]
    }
})

JSON

This property collects JSON data from the user.

Example:

Property.Json({
    displayName: 'Data',
    description: 'Enter JSON data',
    required: true,
    defaultValue: {"key": "value"}
})

Dictionary

This property collects key-value pairs from the user.

Example:

Property.Object({
    displayName: 'Options',
    description: 'Enter key-value pairs',
    required: true,
    defaultValue: {
        key1: 'value1',
        key2: 'value2'
    }
})

File

This property collects a file from the user, either by providing a URL or uploading a file.

Example:

Property.File({
    displayName: 'File',
    description: 'Upload a file',
    required: true
})

Array of Strings

This property collects an array of strings from the user.

Example:

Property.Array({
    displayName: 'Tags',
    description: 'Enter tags',
    required: false,
    defaultValue: ['tag1', 'tag2']
})

Array of Fields

This property collects an array of objects from the user.

Example:

Property.Array({
    displayName: 'Fields',
    description: 'Enter fields',
    properties: {
        fieldName: Property.ShortText({
          displayName: 'Field Name',
          required: true,
        }),
        fieldType: Property.StaticDropdown({
          displayName: 'Field Type',
          required: true,
          options: {
            options: [
              { label: 'TEXT', value: 'TEXT' },
              { label: 'NUMBER', value: 'NUMBER' },
            ],
          },
        }),
    },
    required: false,
    defaultValue:[]
})

Dynamic Data Properties

These properties provide more advanced options for collecting user input.

Dropdown

This property allows for dynamically loaded options based on the user’s input.

Example:

Property.Dropdown({
    displayName: 'Options',
    description: 'Select an option',
    required: true,
    refreshers: ['auth'],
    refreshOnSearch: false,
    options: async ({auth}, {searchValue}) => {
        // Search value only works when refreshOnSearch is true
        if (!auth) {
            return {
                disabled: true
            };
        }
        return {
            options: [
                {
                    label: 'Option One',
                    value: '1'
                },
                {
                    label: 'Option Two',
                    value: '2'
                }
            ]
        };
    }
})

When accessing the Piece auth, be sure to use exactly auth as it is hardcoded. However, for other properties, use their respective names.

Multi-Select Dropdown

This property allows for multiple selections from dynamically loaded options.

Example:

Property.MultiSelectDropdown({
    displayName: 'Options',
    description: 'Select one or more options',
    required: true,
    refreshers: ['auth'],
    options: async ({auth}) => {
        if (!auth) {
            return {
                disabled: true
            };
        }
        return {
            options: [
                {
                    label: 'Option One',
                    value: '1'
                },
                {
                    label: 'Option Two',
                    value: '2'
                }
            ]
        };
    }
})

When accessing the Piece auth, be sure to use exactly auth as it is hardcoded. However, for other properties, use their respective names.

Dynamic Properties

This property is used to construct forms dynamically based on API responses or user input.

Example:

Property.DynamicProperties({
    description: 'Dynamic Form',
    displayName: 'Dynamic Form',
    required: true,
    refreshers: ['authentication'],
    props: async (propsValue) => {
        const authentication

 = propsValue['authentication'];
        const apiEndpoint = 'https://someapi.com';
        const response = await fetch(apiEndpoint);
        const data = await response.json();
        
        const properties = {
            prop1: Property.ShortText({
                displayName: 'Property 1',
                description: 'Enter property 1',
                required: true
            }),
            prop2: Property.Number({
                displayName: 'Property 2',
                description: 'Enter property 2',
                required: false
            })
        };
        
        return properties;
    }
})