Editing package.json

Every function has a package.json file where you can specify user-friendly labels and descriptions for the function, along with what type of inputs (parameters) the function expects. For NodeJS functions this also allows you to specify what NPM dependencies the function should include.

Clay uses the metadata in the package.json file in order to be able to present a user-friendly interface to invoke the function with the appropriate Input Fields (parameters). We also use the information about what inputs (parameters) a function expects in order to make it easy to connect your function in Workflows & Bases.

Below is a brief description of the keys we support. Further down there is also a more in-depth guide to specifying the Input Fields (Parameters) functions take in.

Editable Fields in package.json

displayName

The displayName property allows you to add a more descriptive name to your service. For example, if we have a function with a name property, {youruser}-find-email-addresses-in-text, then a helpful displayName would be "Find Email Addresses In Text". In our workflow views, the more human readable name will then appear when users search for and select this function.

description

The description field gives a short explanation of what this service does. Like the displayName property, the description helps give a more user-friendly explanation of what the function does. For example, for our find-email-addresses-in-text function our description might be:

"description": "Given some text tries finds email addresses in that text and returns information about those addresses and where they occur in the text"

parameters

For any given function, you can specify what parameters the function takes in. Function parameters provide a user-friendly way to use your function inside of Bases and Workflows. Here's the syntax for defining parameters:

"parameters":[
    	{
    		// name (required)
    		// The parameters variable name, you'll be able to reference 
    		// this in your code as event.vars.textToSearch  
    		"name": "textToSearch",
    		
    		// label (optional)
    		// The user-friendly name which appears in the Clay UI for Bases & Workflows
    		"label": "Text to Search"
    
    		// description (optional)
    		// A user-friendly description of what this input field is.
    		"description": "The text to search for email addresses"
    
    		// type (optional)
    		// The type of inputField. For a list of supported inputField types refer to the section below. 
    		// If the type is not specified it defaults to text.
    		"type": "text"
    	
    		// placholder (optional)
    		// An example value to help users understand what they might enter.
    		"placeholder" : "This sample text contains an email: email@clay.run"	
    
    		// required (optional)
    		// By default, fields are not required, i.e. required is set to false
    		"required" : "true"
    	}
    ]

envs (Environment Variables)

The envs field allows you to specify private environment variables that are required for the function. Clay will generate a UI for editing the environment variables in a secure way. They are made available to your function as process.envs.{yourEnvironmentVariableKey}

For example, the value you bind to companyLookupServiceApiToken below will be available in your function's code as: process.envs.companyLookupServiceApiToken

"envs": [
    "companyLookupServiceApiToken"
]

Once you've added the name of an environment variable to the envs array, you'll notice on the right side of the code-editor that you can now add the value bindings too

Binding Environment Variables

Non-Editable Fields in package.json

There are a few fields that are included in the package.json which are just standard NPM fields that are not editable, and not-used by the Clay platform.

name

The name field is not-editable, but corresponds to the unique function identifier used internally by the Clay platform to generate a unique API endpoint for the function.

author

The author field is standard NPM package data that is included but is not used by the Clay platform.

scripts

The scripts field is standard NPM package data that is included but is not used by the Clay platform.