ApplicationInstall

Overview #

ApplicationInstall represents a user's installation of an application. It stores all user-specific configuration, credentials, API keys, OAuth tokens, and settings. In connectors, you use ApplicationInstall to access the credentials needed to authenticate with external APIs.

Purpose:

Store user-specific application settings and credentials
Provide access to API keys, tokens, and authentication data
Track installation status (enabled/disabled)
Manage OAuth token expiration

Location: orchesty-nodejs-sdk/lib/Application/Database/ApplicationInstall.ts

When to Use #

You access ApplicationInstall in connectors when you need:

API credentials: API keys, tokens, passwords
User settings: Form field values, configuration options
OAuth tokens: Access tokens, refresh tokens
User context: Which user is running the connector

Typical flow:

Get ApplicationInstall via getApplicationInstallFromProcess(dto)
Access settings via getSettings()
Extract credentials from specific form (e.g., CoreFormsEnum.AUTHORIZATION_FORM)
Use credentials in API requests

Core Properties #

Property	Type	Description
`user`	`string`	User ID who installed the application
`key`	`string`	Application name/key
`settings`	`IApplicationSettings`	All application settings (encrypted)
`nonEncryptedSettings`	`IApplicationSettings`	Non-sensitive settings
`enabled`	`boolean`	Whether the installation is active
`deleted`	`boolean`	Whether the installation is deleted
`created`	`Date`	When the installation was created
`updated`	`Date`	Last update timestamp
`expires`	`Date \| undefined`	Token expiration (for OAuth)

Methods #

Settings Methods #

getSettings() #

public getSettings(): IApplicationSettings

Returns all application settings (decrypted). This is where you find API keys, tokens, passwords, and form field values.

Returns: IApplicationSettings - Object with form data organized by form key

Structure:

{
  "authForm": {
    "api_key": "xxx",
    "username": "user",
    "password": "pass"
  },
  "configForm": {
    "endpoint": "https://api.example.com",
    "timeout": "30"
  }
}

Example:

const settings = appInstall.getSettings();
const apiKey = settings['authForm']['api_key'];

setSettings() #

public setSettings(settings?: IApplicationSettings): this

Replaces all settings.

Parameters:

Parameter	Type	Description
`settings`	`IApplicationSettings \| undefined`	New settings object

Returns: this - Fluent interface

addSettings() #

public addSettings(setting: IApplicationSettings): this

Merges new settings with existing ones (deep merge).

Parameters:

Parameter	Type	Description
`setting`	`IApplicationSettings`	Settings to merge

Returns: this - Fluent interface

Example:

appInstall.addSettings({
  authForm: {
    token: 'new-token-value'
  }
});

getNonEncryptedSettings() #

public getNonEncryptedSettings(): IApplicationSettings

Returns non-sensitive settings (not encrypted in database).

Returns: IApplicationSettings - Non-encrypted settings

Use case: Store non-sensitive configuration that doesn't need encryption (e.g., API endpoints, feature flags).

addNonEncryptedSettings() #

public addNonEncryptedSettings(nonEncryptedSettings: IApplicationSettings): this

Merges non-encrypted settings.

Parameters:

Parameter	Type	Description
`nonEncryptedSettings`	`IApplicationSettings`	Settings to merge

Returns: this - Fluent interface

User and Name Methods #

getUser() #

public getUser(): string

Returns the user ID who installed the application.

Returns: string - User identifier

Example:

const userId = appInstall.getUser();
console.log(`Processing for user: ${userId}`);

setUser() #

public setUser(user: string): this

Sets the user ID.

Parameters:

Parameter	Type	Description
`user`	`string`	User identifier

Returns: this - Fluent interface

getName() #

public getName(): string

Returns the application name/key.

Returns: string - Application identifier

Example:

const appName = appInstall.getName();
// e.g., "hubspot", "salesforce", "slack"

setName() #

public setName(name: string): this

Sets the application name.

Parameters:

Parameter	Type	Description
`name`	`string`	Application identifier

Returns: this - Fluent interface

State Methods #

isEnabled() #

public isEnabled(): boolean

Checks if the installation is enabled.

Returns: boolean - True if enabled

Example:

if (!appInstall.isEnabled()) {
    throw new Error('Application is disabled');
}

setEnabled() #

public setEnabled(enabled: boolean): this

Sets the enabled state.

Parameters:

Parameter	Type	Description
`enabled`	`boolean`	Enable/disable flag

Returns: this - Fluent interface

Timestamp Methods #

getCreated() #

public getCreated(): Date

Returns when the installation was created.

Returns: Date - Creation timestamp

getUpdated() #

public getUpdated(): Date

Returns when the installation was last updated.

Returns: Date - Last update timestamp

setUpdated() #

public setUpdated(): this

Sets the updated timestamp to current time.

Returns: this - Fluent interface

OAuth Token Methods #

getExpires() #

public getExpires(): Date | undefined

Returns the OAuth token expiration time.

Returns: Date | undefined - Expiration timestamp or undefined

Example:

const expires = appInstall.getExpires();
if (expires && expires < new Date()) {
    console.log('Token expired, need to refresh');
}

setExpires() #

public setExpires(expires?: Date): this

Sets the token expiration time.

Parameters:

Parameter	Type	Description
`expires`	`Date \| undefined`	Expiration timestamp

Returns: this - Fluent interface

Usage Examples #

Getting API Credentials #

import CoreFormsEnum from '../../lib/Application/Base/CoreFormsEnum';

export default class HubspotConnector extends AConnector {
    
    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        // Get application installation
        const appInstall = await this.getApplicationInstallFromProcess(dto);
        
        // Get settings
        const settings = appInstall.getSettings();
        
        // Extract API key from authorization form
        const authForm = settings[CoreFormsEnum.AUTHORIZATION_FORM];
        const apiKey = authForm['api_key'];
        
        // Use the API key in request
        const requestDto = new RequestDto(
            'https://api.hubapi.com/contacts/v1/lists/all',
            HttpMethods.GET,
            dto
        );
        requestDto.setHeaders({
            'Authorization': `Bearer ${apiKey}`
        });
        
        const responseDto = await this.getSender().send(requestDto);
        dto.setData(responseDto.getBody());
        
        return dto;
    }
}

Getting Form Settings #

export default class CustomConnector extends AConnector {
    
    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        const appInstall = await this.getApplicationInstallFromProcess(dto);
        const settings = appInstall.getSettings();
        
        // Get credentials from auth form
        const authForm = settings[CoreFormsEnum.AUTHORIZATION_FORM];
        const username = authForm['user'];
        const password = authForm['password'];
        
        // Get configuration from custom form
        const configForm = settings['configForm'];
        const endpoint = configForm['endpoint'];
        const timeout = parseInt(configForm['timeout'], 10);
        
        // Use the configuration
        const requestDto = new RequestDto(endpoint, HttpMethods.GET, dto);
        requestDto.setTimeout(timeout * 1000);
        requestDto.setAuth(username, password);
        
        const responseDto = await this.getSender().send(requestDto);
        dto.setData(responseDto.getBody());
        
        return dto;
    }
}

OAuth2 Token Access #

import { TOKEN } from '../../lib/Authorization/Type/Basic/ABasicApplication';
import { ACCESS_TOKEN } from '../../lib/Authorization/Provider/OAuth2/OAuth2Provider';

export default class OAuth2Connector extends AConnector {
    
    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        const appInstall = await this.getApplicationInstallFromProcess(dto);
        const settings = appInstall.getSettings();
        
        // Get OAuth2 token
        const authForm = settings[CoreFormsEnum.AUTHORIZATION_FORM];
        const token = authForm[TOKEN];
        const accessToken = token[ACCESS_TOKEN];
        
        // Check if token is expired
        const expires = appInstall.getExpires();
        if (expires && expires < new Date()) {
            // Token expired - application should handle refresh
            throw new Error('OAuth token expired');
        }
        
        // Use the access token
        const requestDto = new RequestDto(
            'https://api.example.com/data',
            HttpMethods.GET,
            dto
        );
        requestDto.setHeaders({
            'Authorization': `Bearer ${accessToken}`
        });
        
        const responseDto = await this.getSender().send(requestDto);
        dto.setData(responseDto.getBody());
        
        return dto;
    }
}

Checking Authorization #

export default class SecureConnector extends AConnector {
    
    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        const appInstall = await this.getApplicationInstallFromProcess(dto);
        
        // Check if application is enabled
        if (!appInstall.isEnabled()) {
            dto.setStopProcess(
                ResultCode.STOP_AND_FAILED,
                'Application is disabled for this user'
            );
            return dto;
        }
        
        // Get application instance to check authorization
        const app = this.getApplication();
        if (!app.isAuthorized(appInstall)) {
            dto.setStopProcess(
                ResultCode.STOP_AND_FAILED,
                'Application is not properly authorized'
            );
            return dto;
        }
        
        // Proceed with processing...
        const settings = appInstall.getSettings();
        // ... rest of your logic
        
        return dto;
    }
}

Non-Encrypted Settings #

export default class ConfigurableConnector extends AConnector {
    
    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        const appInstall = await this.getApplicationInstallFromProcess(dto);
        
        // Get non-sensitive configuration (not encrypted)
        const nonEncrypted = appInstall.getNonEncryptedSettings();
        const apiEndpoint = nonEncrypted['apiEndpoint'];
        const retryCount = nonEncrypted['retryCount'];
        const debugMode = nonEncrypted['debugMode'];
        
        // Get sensitive credentials (encrypted)
        const settings = appInstall.getSettings();
        const apiKey = settings[CoreFormsEnum.AUTHORIZATION_FORM]['api_key'];
        
        // Use both configurations
        if (debugMode) {
            console.log(`Calling: ${apiEndpoint}`);
        }
        
        const requestDto = new RequestDto(apiEndpoint, HttpMethods.GET, dto);
        requestDto.setHeaders({ 'X-API-Key': apiKey });
        
        const responseDto = await this.getSender().send(requestDto);
        dto.setData(responseDto.getBody());
        
        return dto;
    }
}

Common Patterns #

Pattern 1: Safe Credential Access #

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const appInstall = await this.getApplicationInstallFromProcess(dto);
    const settings = appInstall.getSettings();
    
    // Safely access nested settings
    const authForm = settings[CoreFormsEnum.AUTHORIZATION_FORM] || {};
    const apiKey = authForm['api_key'];
    
    if (!apiKey) {
        dto.setStopProcess(
            ResultCode.STOP_AND_FAILED,
            'API key not configured'
        );
        return dto;
    }
    
    // Use the API key...
    return dto;
}

Pattern 2: Multiple Credential Types #

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const appInstall = await this.getApplicationInstallFromProcess(dto);
    const settings = appInstall.getSettings();
    const authForm = settings[CoreFormsEnum.AUTHORIZATION_FORM];
    
    let headers: Record<string, string> = {};
    
    // Support multiple auth methods
    if (authForm['api_key']) {
        headers['X-API-Key'] = authForm['api_key'];
    } else if (authForm['token']) {
        headers['Authorization'] = `Bearer ${authForm['token'][ACCESS_TOKEN]}`;
    } else if (authForm['user'] && authForm['password']) {
        const credentials = Buffer.from(
            `${authForm['user']}:${authForm['password']}`
        ).toString('base64');
        headers['Authorization'] = `Basic ${credentials}`;
    }
    
    const requestDto = new RequestDto(
        'https://api.example.com/data',
        HttpMethods.GET,
        dto
    );
    requestDto.setHeaders(headers);
    
    const responseDto = await this.getSender().send(requestDto);
    dto.setData(responseDto.getBody());
    
    return dto;
}

Pattern 3: User Context #

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const appInstall = await this.getApplicationInstallFromProcess(dto);
    
    // Get user context
    const userId = appInstall.getUser();
    const appName = appInstall.getName();
    
    console.log(`User ${userId} is running ${appName}`);
    
    // Use for logging, tracking, or user-specific logic
    dto.addHeader('X-User-ID', userId);
    dto.addHeader('X-App-Name', appName);
    
    // Process with user context...
    return dto;
}

Next Steps #

Now that you understand ApplicationInstall, learn how to create applications that define these settings:

ABasicApplication - Create apps with basic/token authentication
AOAuth2Application - Create apps with OAuth2
Form - Build configuration forms
CoreFormsEnum - Standard form identifiers
AConnector - Use ApplicationInstall in connectors

ApplicationInstall

Overview #

When to Use #

Core Properties #

Methods #

Settings Methods #

getSettings() #

setSettings() #

addSettings() #

getNonEncryptedSettings() #

addNonEncryptedSettings() #

User and Name Methods #

getUser() #

setUser() #

getName() #

setName() #

State Methods #

isEnabled() #

setEnabled() #

Timestamp Methods #

getCreated() #

getUpdated() #

setUpdated() #

OAuth Token Methods #

getExpires() #

setExpires() #

Usage Examples #

Getting API Credentials #

Getting Form Settings #

OAuth2 Token Access #

Checking Authorization #

Non-Encrypted Settings #

Common Patterns #

Pattern 1: Safe Credential Access #

Pattern 2: Multiple Credential Types #

Pattern 3: User Context #

Next Steps #

See Also #