validateOptions

validate user options on your integration before they save them

Summary

Optional function validateOptions(userOptions, callback)

Parameters	Description
userOptions	a user options object keyed on the option's key property
callback	the callback function to execute which returns any validation errors

The validateOptions method is used to validate user options specified in the config.js file. Anytime a user attempts to save user options or subscribe to an integration the validateOptions method is called. You should use this method to ensure that options set by users and administrators are valid. This is an optional method which does not have to be implemented in your integration.

Parameters

userOptions

userOptions is an object keyed on the option key property that contains the full option object specified in the config.js with an added value property that contains the value for the option. The value for the option is what should be validated.

// example userOptions
{
    apiKey: {
        key         : "apiKey",
        name        : "Sample API Key",
        description : "The API Key for your Sample Integration",
        type        : "text",
        default     : "",            
        userCanEdit : true,
        adminOnly   : false,
        value: "jkasdiojasio1j23oij123"
    }   
}

Note that the userOptions object will always contain all options as specified in the config.js file even if the value has not been provided.

When accessing options from the userOptions object make sure you access the value property to get the current value of the option.

// Accessing the value of the option `apiKey`
function validateOptions(userOptions, callback){
    let apiKey = userOptions.apiKey.value;    
}

callback(error, validationErrors)

The second parameter for the validateOptions method is a callback function that returns as its first parameter an error object and as its second parameter an array of validation errors.

error

The callback should method should return an error object as the first parameter if there was an error during validation (this will typically be null unless your validateOptions method performs actions such as performing network requests that might have errors).

validationErrors

The second parameter should be an array of validation error objects (or an empty array if there are no validation errors). The validation error objects should contain a key property that matches the option key that did not validate along with a message property that contains a string literal message to display to the user.

// example validationErrors array
let validationErrors = [
    {
        key         : "apiKey",
        message     : "Sample API Key"
    }   
]

Example

The following is an example that shows a complete validateOptions method. The method validates the apiKey option by ensuring that the apiKey is a string and that the length of the apiKey is not 0.

integration.js

// example validateOptions method
function validateOptions(userOptions, cb) {
    let validationErrors = [];
    if(typeof userOptions.apiKey.value !== 'string' ||
        (typeof userOptions.apiKey.value === 'string' && 
        userOptions.apiKey.value.length === 0)){
        validationErrors.push({
            key: 'apiKey',
            message: 'You must provide an API key'
        })
    }

    cb(null, validationErrors);
}