TryLearn More

Use SIP trunks, WebRTC & Apps

Slash your Phone Bill by 80%

Components - Your Building Blocks

On this topic

Components - Your Building Blocks

Introduction

Components default options

Main building blocks

Menu

User Input

Authentication

Credit Card

Prompt Playback

Record

Record and Email

Transfer

Make Call

Disconnect Call

Get DN Property

Set DN Property

Get Global Property

Set Global Property

Get Extension Status

Get Queue Extensions

Encryption

Database Access

E-Mail Sender

Launch External Script

Read / Write to File

Open a Socket

HTTP Requests

Web Service REST

Web Service (POST)

User Defined Components

See also

Introduction

Components are the main building blocks of a call flow or dialer, and perform basic actions such as playing a prompt, recording audio from the caller, asking for user input, accessing a database and so on. There are two types of components – one with “branches”, such as the Menu component or without – like the Prompt Playback component.

When a component is selected in the designer, the Properties window shows the input properties for it. These are the options you need to set for the component to work, for example the database connection information. Also, some components have output properties which are exposed after execution, containing the execution result, for example the data returned by the database. The public properties created for a user defined component can be used as input and output.

If a red alert sign appears on the top right corner of a component, the component has invalid property values. Click on it to get more details.

Components default options

When you add a component to the designer, it will be automatically configured with the default options you set. You can change the component default values from menu Tools > Options > Component Templates. Please note that the values entered here are constant values, and not expressions, because here we’re not in the context of a project. As a result, constant string values must not contain quotes here.

Main building blocks

The following are the main building blocks available out of the box for your application. You can configure them from the Properties window, or opening the configuration dialog by double clicking the component. When an input property is an expression, click on the button on the right of the text box to open the Expression Editor.

Menu

Menu configuration

This component configures a menu for single digit options. It handles the retry logic when the user enters an invalid option or does not enter any DTMF. Its execution finalizes when a valid option is selected or if all retries have been attempted. The input properties are the following:

  • AllowDtmfInput: True to allow the prompts to be interrupted by a DTMF input. False otherwise.
  • MaxRetryCount: Number of retry attempts for invalid input or timeout. The retry counter is unique, and counts invalid inputs or no inputs using the same counter.
  • Timeout: The time to wait for user input, before playing the specified timeout prompts, in seconds.
  • IsValidOption_N: Specify what happens when the user presses N. It could be a valid or an invalid option. Valid options appear as branches in the designer.
  • InitialPrompts: The list of prompts to play the first time the menu is executed.
  • SubsequentPrompts: The list of prompts to play subsequent times (after timeout or invalid option).
  • TimeoutPrompts: The list of prompts to play when the user does not enter any digit. After playing the timeout prompts, the subsequent prompts will be played.
  • InvalidDigitPrompts: The list of prompts to play when the user enters an invalid digit. After playing the invalid digit prompts, the subsequent prompts will be played.

When the menu ends, the execution continues on one of its branches (a valid option branch or the timeout or invalid option branch). The menu component exposes the following output properties after execution:

  • Result: the result of menu execution. It could be one of the following constant values: MenuResult.Timeout, MenuResult.InvalidOption or MenuResult.ValidOption.

User Input

User input configuration

This component collects information from the caller in the form of DTMF digits. It handles the retry logic when the user enters an invalid digit, fewer digits than expected or does not enter anything at all. The execution finalizes when a valid input is entered by the caller or all the retries have been attempted. The input properties are the following:

  • AllowDtmfInput: True to allow the prompts to be interrupted by a DTMF input. False otherwise.
  • MaxRetryCount: Number of retry attempts for invalid input or timeout. The retry counter is unique, and counts invalid inputs or no inputs using the same counter.
  • InitialPrompts: The list of prompts to play the first time the menu is executed.
  • SubsequentPrompts: The list of prompts to play subsequent times (after timeout or invalid digit).
  • TimeoutPrompts: The list of prompts to play when the user does not enter any digit. After playing the timeout prompts, the subsequent prompts will be played.
  • InvalidDigitPrompts: The list of prompts to play when the user enters invalid digits. After playing the invalid digit prompts, the subsequent prompts will be played.
  • FirstDigitTimeout: The time to wait for the first digit, before playing the specified timeout prompts, in seconds.
  • InterDigitTimeout: The time to wait for subsequent digits, before playing the specified invalid digits prompts, in seconds.
  • FinalDigitTimeout: The time to wait for digits after MinDigits has been reached, before returning the entered data, in seconds.
  • MinDigits: The minimum quantity of digits that must be entered by the user.
  • MaxDigits: The maximum quantity of digits that can be entered by the user.
  • StopDigit: Specifies the digit that the user must press in order to finalize the data entry.
  • IsValidDigit_N: Specifies what happens when the user presses N. It could be a valid or an invalid digit.

When the user input ends, execution continues on one of its branches (“Valid Input” or “Invalid Input”). The user input component exposes the following output properties after execution:

  • Result: one of the following values:
  • UserInputResult.Timeout: the user didn’t enter any digit in the last attempt.
  • UserInputResult.InvalidDigits: the user entered an invalid digit or less than MinDigits in the last attempt.
  • UserInputResult.ValidDigits: the user entered valid digits between MinDigits and MaxDigits, optionally terminating the input with the StopDigit.
  • Buffer: the digits entered by the user (not including the StopDigit if it was entered by the user).

Authentication

Authentication configuration

This component collects an ID and a PIN from the caller in the form of DTMF digits. It handles the retry logic when the user enters invalid digits, fewer digits than expected or does not enter anything at all. The execution finalizes when a valid input is entered by the caller for both the ID and the PIN, or all the retries have been attempted. The input properties are the following:

  • MaxRetryCount: Number of retry attempts to enter a valid ID and PIN.
  • IsPinRequired: Specifies if the component should request only an ID, or a PIN as well.
  • RequestIdAllowDtmfInput: When entering the ID, true to allow the prompts to be interrupted by a DTMF input. False otherwise.
  • RequestIdMaxRetryCount: When entering the ID, number of retry attempts for invalid input or timeout. The retry counter is unique, and counts invalid inputs or no inputs using the same counter.
  • RequestIdInitialPrompts: When entering the ID, the list of prompts to play the first time the menu is executed.
  • RequestIdSubsequentPrompts: When entering the ID, the list of prompts to play subsequent times (after timeout or invalid digit).
  • RequestIdTimeoutPrompts: When entering the ID, the list of prompts to play when the user does not enter any digit. After playing the timeout prompts, the subsequent prompts will be played.
  • RequestIdInvalidDigitPrompts: When entering the ID, the list of prompts to play when the user enters invalid digits. After playing the invalid digit prompts, the subsequent prompts will be played.
  • RequestIdFirstDigitTimeout: When entering the ID, the time to wait for the first digit, before playing the specified timeout prompts, in seconds.
  • RequestIdInterDigitTimeout: When entering the ID, the time to wait for subsequent digits, before playing the specified invalid digits prompts, in seconds.
  • RequestIdFinalDigitTimeout: When entering the ID, the time to wait for digits after MinDigits has been reached, before returning the entered data, in seconds.
  • RequestIdMinDigits: When entering the ID, the minimum quantity of digits that must be entered by the user.
  • RequestIdMaxDigits: When entering the ID, the maximum quantity of digits that can be entered by the user.
  • RequestIdStopDigit: When entering the ID, specifies the digit that the user must press in order to finalize the data entry.
  • RequestIdIsValidDigit_N: When entering the ID, specifies what happens when the user presses N. It could be a valid or an invalid digit.
  • RequestPinAllowDtmfInput: When entering the PIN, true to allow the prompts to be interrupted by a DTMF input. False otherwise.
  • RequestPinMaxRetryCount: When entering the PIN, number of retry attempts for invalid input or timeout. The retry counter is unique, and counts invalid inputs or no inputs using the same counter.
  • RequestPinInitialPrompts: When entering the PIN, the list of prompts to play the first time the menu is executed.
  • RequestPinSubsequentPrompts: When entering the PIN, the list of prompts to play subsequent times (after timeout or invalid digit).
  • RequestPinTimeoutPrompts: When entering the PIN, the list of prompts to play when the user does not enter any digit. After playing the timeout prompts, the subsequent prompts will be played.
  • RequestPinInvalidDigitPrompts: When entering the PIN, the list of prompts to play when the user enters invalid digits. After playing the invalid digit prompts, the subsequent prompts will be played.
  • RequestPinFirstDigitTimeout: When entering the PIN, the time to wait for the first digit, before playing the specified timeout prompts, in seconds.
  • RequestPinInterDigitTimeout: When entering the PIN, the time to wait for subsequent digits, before playing the specified invalid digits prompts, in seconds.
  • RequestPinFinalDigitTimeout: When entering the PIN, the time to wait for digits after MinDigits has been reached, before returning the entered data, in seconds.
  • RequestPinMinDigits: When entering the PIN, the minimum quantity of digits that must be entered by the user.
  • RequestPinMaxDigits: When entering the PIN, the maximum quantity of digits that can be entered by the user.
  • RequestPinStopDigit: When entering the PIN, specifies the digit that the user must press in order to finalize the data entry.
  • RequestPinIsValidDigit_N: When entering the PIN, specifies what happens when the user presses N. It could be a valid or an invalid digit.

When the Authentication component collects the ID and PIN, the execution continues on the “Valid Input” branch, and the component exposes the following output properties:

  • ID: the digits entered by the user for the ID (not including the StopDigit if it was entered by the user).
  • PIN: the digits entered by the user for the PIN (not including the StopDigit if it was entered by the user).
  • Validated: a boolean property that must be set to true in order to tell the Authentication component that the ID and PIN are valid, so it avoids asking again for this information.

On the other hand, when the Authentication component can’t collect the ID or PIN, the execution continues on the “Invalid Input” branch, where you can play a message for example, and then the component will retry asking for the ID and PIN, until the MaxRetryCount is reached.

Credit Card

Credit Card configuration

This component collects a credit card number, expiration date and security code from the caller in the form of DTMF digits. It handles the retry logic when the user enters invalid digits, fewer digits than expected or does not enter anything at all. The execution finalizes when a valid input is entered by the caller for the credit card number, the expiration date and the security code, or all the retries have been attempted. The input properties are the following:

  • MaxRetryCount: Number of retry attempts to enter a valid combination of credit card number, expiration date and security code.
  • IsExpirationRequired: Specifies if the component should request only the credit card number, or the expiration date as well.
  • IsSecurityCodeRequired: Specifies if the component should request only the credit card number and expiration date, or the security code as well.
  • RequestNumberAllowDtmfInput: When entering the credit card number, true to allow the prompts to be interrupted by a DTMF input. False otherwise.
  • RequestNumberMaxRetryCount: When entering the credit card number, number of retry attempts for invalid input or timeout. The retry counter is unique, and counts invalid inputs or no inputs using the same counter.
  • RequestNumberInitialPrompts: When entering the credit card number, the list of prompts to play the first time the menu is executed.
  • RequestNumberSubsequentPrompts: When entering the credit card number, the list of prompts to play subsequent times (after timeout or invalid digit).
  • RequestNumberTimeoutPrompts: When entering the credit card number, the list of prompts to play when the user does not enter any digit. After playing the timeout prompts, the subsequent prompts will be played.
  • RequestNumberInvalidDigitPrompts: When entering the credit card number, the list of prompts to play when the user enters invalid digits. After playing the invalid digit prompts, the subsequent prompts will be played.
  • RequestNumberFirstDigitTimeout: When entering the credit card number, the time to wait for the first digit, before playing the specified timeout prompts, in seconds.
  • RequestNumberInterDigitTimeout: When entering the credit card number, the time to wait for subsequent digits, before playing the specified invalid digits prompts, in seconds.
  • RequestNumberFinalDigitTimeout: When entering the credit card number, the time to wait for digits after MinDigits has been reached, before returning the entered data, in seconds.
  • RequestNumberMinDigits: When entering the credit card number, the minimum quantity of digits that must be entered by the user.
  • RequestNumberMaxDigits: When entering the credit card number, the maximum quantity of digits that can be entered by the user.
  • RequestNumberStopDigit: When entering the credit card number, specifies the digit that the user must press in order to finalize the data entry.
  • RequestNumberIsValidDigit_N: When entering the credit card number, specifies what happens when the user presses N. It could be a valid or an invalid digit.
  • RequestExpirationAllowDtmfInput: When entering the expiration date, true to allow the prompts to be interrupted by a DTMF input. False otherwise.
  • RequestExpirationMaxRetryCount: When entering the expiration date, number of retry attempts for invalid input or timeout. The retry counter is unique, and counts invalid inputs or no inputs using the same counter.
  • RequestExpirationInitialPrompts: When entering the expiration date, the list of prompts to play the first time the menu is executed.
  • RequestExpirationSubsequentPrompts: When entering the expiration date, the list of prompts to play subsequent times (after timeout or invalid digit).
  • RequestExpirationTimeoutPrompts: When entering the expiration date, the list of prompts to play when the user does not enter any digit. After playing the timeout prompts, the subsequent prompts will be played.
  • RequestExpirationInvalidDigitPrompts: When entering the expiration date, the list of prompts to play when the user enters invalid digits. After playing the invalid digit prompts, the subsequent prompts will be played.
  • RequestExpirationFirstDigitTimeout: When entering the expiration date, the time to wait for the first digit, before playing the specified timeout prompts, in seconds.
  • RequestExpirationInterDigitTimeout: When entering the expiration date, the time to wait for subsequent digits, before playing the specified invalid digits prompts, in seconds.
  • RequestExpirationFinalDigitTimeout: When entering the expiration date, the time to wait for digits after MinDigits has been reached, before returning the entered data, in seconds.
  • RequestExpirationMinDigits: When entering the expiration date, the minimum quantity of digits that must be entered by the user.
  • RequestExpirationMaxDigits: When entering the expiration date, the maximum quantity of digits that can be entered by the user.
  • RequestExpirationStopDigit: When entering the expiration date, specifies the digit that the user must press in order to finalize the data entry.
  • RequestExpirationIsValidDigit_N: When entering the expiration date, specifies what happens when the user presses N. It could be a valid or an invalid digit.
  • RequestSecurityCodeAllowDtmfInput: When entering the security code, true to allow the prompts to be interrupted by a DTMF input. False otherwise.
  • RequestSecurityCodeMaxRetryCount: When entering the security code, number of retry attempts for invalid input or timeout. The retry counter is unique, and counts invalid inputs or no inputs using the same counter.
  • RequestSecurityCodeInitialPrompts: When entering the security code, the list of prompts to play the first time the menu is executed.
  • RequestSecurityCodeSubsequentPrompts: When entering the security code, the list of prompts to play subsequent times (after timeout or invalid digit).
  • RequestSecurityCodeTimeoutPrompts: When entering the security code, the list of prompts to play when the user does not enter any digit. After playing the timeout prompts, the subsequent prompts will be played.
  • RequestSecurityCodeInvalidDigitPrompts: When entering the security code, the list of prompts to play when the user enters invalid digits. After playing the invalid digit prompts, the subsequent prompts will be played.
  • RequestSecurityCodeFirstDigitTimeout: When entering the security code, the time to wait for the first digit, before playing the specified timeout prompts, in seconds.
  • RequestSecurityCodeInterDigitTimeout: When entering the security code, the time to wait for subsequent digits, before playing the specified invalid digits prompts, in seconds.
  • RequestSecurityCodeFinalDigitTimeout: When entering the security code, the time to wait for digits after MinDigits has been reached, before returning the entered data, in seconds.
  • RequestSecurityCodeMinDigits: When entering the security code, the minimum quantity of digits that must be entered by the user.
  • RequestSecurityCodeMaxDigits: When entering the security code, the maximum quantity of digits that can be entered by the user.
  • RequestSecurityCodeStopDigit: When entering the security code, specifies the digit that the user must press in order to finalize the data entry.
  • RequestSecurityCodeIsValidDigit_N: When entering the security code, specifies what happens when the user presses N. It could be a valid or an invalid digit.

When the Credit Card component collects the Number, Expiration Date and Security Code, the execution continues on the “Valid Input” branch, and the component exposes the following output properties:

  • Number: the digits entered by the user for the credit card number (not including the StopDigit if it was entered by the user).
  • Expiration: the digits entered by the user for the expiration date (not including the StopDigit if it was entered by the user).
  • SecurityCode: the digits entered by the user for the security code (not including the StopDigit if it was entered by the user).
  • Validated: a boolean property that must be set to true in order to tell the Credit Card component that the Number, Expiration Date and Security Code are valid, so it avoids asking again for this information.

On the other hand, when the Credit Card component can’t collect the Number, Expiration Date or Security Code, the execution continues on the “Invalid Input” branch, where you can play a message for example, and then the component will retry asking for the Number, Expiration Date and Security Code, until the MaxRetryCount is reached.

Prompt Playback

This component allows playing a list of prompts. The input properties are the following:

  • AllowDtmfInput: True to allow the prompts to be interrupted by a DTMF input. False otherwise.
  • Prompts: The list of prompts to play when the component is executed.

Record

Record configuration

This component records audio from the caller. Before recording, the list of prompts specified is played. If the Beep property is set, a beep is played to the caller after the prompts and before starting recording. The recording will finish when the seconds specified in MaxTime are reached, or the caller presses a DTMF key when the TerminateByDtmf property is set. The recorded audio can be automatically saved to a file. The input properties are the following:

  • Beep: If true, a tone is emitted just before recording starts.
  • Prompts: The list of prompts to play before recording (available prompt types are described in Prompt Types).
  • MaxTime: The maximum duration to record, in seconds.
  • TerminateByDtmf: If true, any DTMF key press will stop the recording.
  • SaveToFile: If true, the recorded audio will be saved to the file specified by FileName. The value is an expression.
  • FileName: The name of the file where the recording must be saved. Only valid when SaveToFile evaluates to true. The value is an expression.

When the recording ends, execution continues on one of its branches (“Audio Recorded” or “Nothing Recorded”). The record component exposes the following output properties after execution:

  • Result: the recording result:
  • RecordResult.NothingRecorded: no audio recorded.
  • RecordResult.StopDigit: recording was stopped by a DTMF key press.
  • RecordResult.Completed: recording was stopped by reaching the maximum audio length.
  • Duration: the duration of the recorded audio in seconds.
  • StopDigit: the DTMF digit pressed by the user when Result = RecordResult.StopDigit.
  • AudioId: a variable containing the audio, which can be used to play it back to the user.

Record and Email

Record and Email configuration

This component records audio from the caller and sends it attached to an email message. Before recording, the list of prompts specified is played. If the Beep property is set, a beep is played to the caller after the prompts and before starting recording. The recording will finish when the seconds specified in MaxTime are reached, the caller presses a DTMF key when the TerminateByDtmf property is set, or when the caller hangs up. The input properties are the following:

  • Beep: If true, a tone is emitted just before recording starts.
  • Prompts: The list of prompts to play before recording (available prompt types are described in Prompt Types).
  • MaxTime: The maximum duration to record, in seconds.
  • TerminateByDtmf: If true, any DTMF key press will stop the recording.
  • Use 3CX Server connection settings: check this option to use the 3CX server mail settings, or leave it unchecked to enter the connection information here. Please note that this will not work if you use the 3CX SMTP Server, in that case you will need to add your own server settings.
  • SMTP Server: The SMTP Server name or IP address. The value is an expression.
  • Server Port: The port number where the connection to the SMTP server must be established. The value is an expression.
  • EnableSSL: Specify if the connection to the SMTP Server must be done using SSL or not. The value is an expression.
  • UserName: The username to use when connecting to the SMTP Server. The value is an expression.
  • Password: The password to use when connecting to the SMTP Server. The value is an expression.
  • From: The e-mail address to use in the 'from' field of the message. The value is an expression.
  • To: The e-mail addresses to use in the 'to' field of the message, separated by comma in case of being more than one. The value is an expression.
  • CC: The e-mail addresses to use in the 'cc' field of the message, separated by comma in case of being more than one. The value is an expression.
  • BCC: The e-mail addresses to use in the 'bcc' field of the message, separated by comma in case of being more than one. The value is an expression.
  • Subject: The subject of the e-mail message. The value is an expression.
  • Body Is HTML: Indicates if the body text is HTML or plain text.
  • Body: The body of the e-mail message. The value is an expression.
  • Priority: The priority of the e-mail message.

Transfer

Transfer component configuration

Use this component to transfer the call. Only blind transfer is supported. The call will be disconnected from the CFD application and transferred to the specified destination. The input properties are the following:

  • Destination: The destination number where the call must be transferred. The value is an expression.

When the transfer is completed, the execution continues on the disconnect handler flow, as the call is disconnected from the application.

Make Call

Make Call component configuration

This component allows making an outbound call between two parties. The call made will not be handled by this voice application. The component instructs 3CX to call the number specified in Origin, put it on hold and then make a call to the number specified in Destination. When both parties are connected, 3CX will connect them together. This component is useful for example to make a call from an internal extension to an external number. The input properties are the following:

  • Origin: The number of the first party of the call. The value is an expression, so you may for example get the number from a database.
  • Destination: The number of the second party of the call. The value is an expression, so you may for example get the number from a database.

 

Disconnect Call

This component disconnects the current call. It has no special input properties and does not expose any output property after its execution. When this component execution ends, the execution continues on the Disconnect handler flow.

Get DN Property

Get DN Property configuration

This component allows reading a property value for a specific DN. The input properties are the following:

  • Extension: The extension number of the DN from which we will be reading the property. The value is an expression.
  • Property Name: The name of the property to read. The value is an expression.

The Get DN Property component exposes the following output properties after execution:

  • PropertyValue: contains the value of the property.

Important note: property names must be upper case.

Set DN Property

Set DN Property configuration

This component allows setting a property value for a specific DN. The input properties are the following:

  • Extension: The extension number of the DN to which we will be setting the property value. The value is an expression.
  • Property Name: The name of the property to set. The value is an expression.
  • Property Value: The value of the property to set. The value is an expression.

The Set DN Property component doesn’t expose any output property after execution.

Important note: property names must be upper case.

Get Global Property

Get Global Property configuration

This component allows reading a global property value. The input properties are the following:

  • Property Name: The name of the property to read. The value is an expression.

The Get Global Property component exposes the following output properties after execution:

  • PropertyValue: contains the value of the property.

Important note: property names must be upper case.

Set Global Property

Set Global Property configuration

This component allows setting a global property value. The input properties are the following:

  • Property Name: The name of the property to set. The value is an expression.
  • Property Value: The value of the property to set. The value is an expression.

The Set Global Property component doesn’t expose any output property after execution.

Important note: property names must be upper case.

Get Extension Status

Get Extension Status configuration

This component allows getting the status of a specific extension. It just needs the extension number as input, and it will tell if the extension is in a call or not, and the current profile considering overrides. The input properties are the following:

  • Extension: The extension number from which we want to get the status. The value is an expression.

The Get Extension Status component exposes the following output properties after execution:

  • IsInCall: contains a boolean indicating if the extension is currently handling a call or not.
  • CurrentProfile: a FwdProfile object (check the 3CX Call Control API for more details) with the information of the current profile, considering overrides.
  • CurrentProfileName: a string with the current profile name, considering overrides.

Get Queue Extensions

Get Queue Extensions configuration

This component allows getting the extensions / agents for a queue. We can configure it to return all the extensions for the queue, only the ones that are logged in, or the ones that are logged out. The input properties are the following:

  • Queue Extension: The extension number of the queue from which we want to get the list of extensions. The value is an expression.
  • Query Type: the type of query we want to do. Select “All” to return all the extensions for this queue, select “LoggedIn” to return the extensions that are logged in to this queue, or select “LoggedOut” to return the extensions that are logged out from this queue.

The Get Queue Extensions component exposes the following output properties after execution:

  • ExtensionList: a list of Extension objects (check the 3CX Call Control API for more details) containing all the extensions that satisfy the type of query performed.
  • ExtensionNumberList: a list of strings with the extension numbers that satisfy the type of query performed.

In order to get the values from the resulting lists, we need to use the following CFD Functions:

  • GET_LIST_ITEM_COUNT: this function will give us the number of items in the list.
  • GET_LIST_ITEM: this function will return the item at a specific index.

Encryption

Cryptography configuration

This component allows encrypting data, decrypting data and performing hash calculations. The supported algorithms are TripleDES for encrypting and decrypting, and the MD5 algorithm that performs hash calculation. The TripleDES algorithm allows encrypting and decrypting text using a known key. The hash calculation is a one way algorithm, and the original value cannot be obtained back from the hash.

The result of the encryption and the MD5 hash calculation is an array of bytes. The CFD needs to encode the array of bytes in order to store them as a String. There are two possible encoding formats: Hexadecimal and Base64. The hexadecimal format consists of the representation of each byte as two characters that represent the byte value in hexadecimal (from 00 to FF). The Base64 format is used to encode the bytes according to that worldwide known format.

When the TripleDES algorithm is used, the key must be a 24 characters string. The text to be processed is an expression that returns a string. The input properties are the following:

  • Algorithm: The algorithm to use. It could be TripleDES or HashMD5.
  • Format: The encoding format to use in order to transform the encrypted stream into text. When encrypting data, this is how the result is codified. When decrypting data, this is how the input text arrives. It could be Hexadecimal or Base64.
  • Action: The action to perform. Only valid when Algorithm is TripleDES. It could be Encrypt or Decrypt.
  • Key: The secret key to be used for the symmetric algorithm. Only valid when Algorithm is TripleDES. It must have a length of 24 characters for TripleDES.
  • Text: The text to encrypt, decrypt or compute hash. The value is an expression.

The Encryption component exposes the following output properties after execution:

  • Result: contains the encryption, decryption or MD5 hash result, encoded according to the specified encryption algorithm.

Database Access

Database Access configuration

This component allows performing operations on SQL Server or PostreSQL databases. You can execute three different kinds of statements: Query, NonQuery and Scalar.

  • Query statements return a list of records. For example, “SELECT * FROM TABLE”.
  • NonQuery statements perform an insert or modification, and return the quantity of affected records. For example, “INSERT VALUES (VALUE1) INTO TABLE”.
  • Scalar statements perform data search but return a unique value. For example, “SELECT COUNT(*) FROM TABLE”.

This component has the following input properties:

  • DatabaseType: The type of the database. It could be SqlServer or PostreSQL.
  • UseConnectionString: True to set a connection string, or False to set each property separately.
  • ConnectionString: The database connection string. Only valid when UseConnectionString is set to True. The value is an expression.
  • Server: The database server name or IP address. Only valid when UseConnectionString is set to False. The value is an expression.
  • Port: The port number where the connection must be established. Only valid when UseConnectionString is set to False. The value is an expression.
  • Database: The database to use when connecting to the Server. Only valid when UseConnectionString is set to False. The value is an expression.
  • UserName: The username to use when connecting to the database. Only valid when UseConnectionString is set to False. The value is an expression.
  • Password: The password to use when connecting to the database. Only valid when UseConnectionString is set to False. The value is an expression.
  • StatementType: The type of the statement. Use Query to execute an SQL statement that returns rows (for example, SELECT). Use NonQuery to execute an SQL statement that doesn't return rows (for example, INSERT, DELETE, UPDATE). Use Scalar to execute an SQL statement that returns a single value (for example, SUM, COUNT).
  • Timeout: The time to wait in seconds before terminating the attempt to execute an SQL statement and generating an error. A value of 0 indicates no limit, and should be avoided because an attempt to execute an SQL statement could wait indefinitely.
  • SqlStatement: The SQL statement to execute, including placeholders for variable parameters.
  • Parameters: The list of parameters to use with the SQL statement.

In some cases, setting the server, port, database, username and password separately is not enough, because you might need some special property to connect to the database. In those cases, it’s possible to set the connection string directly for SQL Server or PostreSQL.

The “SQL Statement” input property might contain variable parts. In order to insert a parameter value into the SQL statement, press the button on the right side of the text box and select the desired parameter. Parameters are set using expressions. In order to create an expression for a parameter, press the ellipsis button on the last column of the grid.

The database access component exposes the following output properties after execution, which contain the processing result according to the type of the selected statement:

  • QueryResult: a table containing every row returned from the database. The expression editor functions GET_TABLE_ROW_COUNT and GET_TABLE_CELL_VALUE allow reading the whole table. The first function returns the quantity of records in the table, so it can be stepped through with the Loop component. The second function allows obtaining the cell value specifying the row and column numbers. Indexes start from zero.
  • NonQueryResult: an integer value containing the number of rows affected.
  • ScalarResult: a string value containing the value returned from the database.

E-Mail Sender

Email Sender configuration

This component allows sending e-mail messages, including attachments. You can use authenticated connections with username and password, specify the sender and different recipient addresses (To, CC or BCC), set the subject and mail body, and attach files. The input properties are the following:

  • Use 3CX Server connection settings: check this option to use the 3CX server mail settings, or leave it unchecked to enter the connection information here. Please note that this will not work if you use the 3CX SMTP Server, in that case you will need to add your own server settings.
  • SMTP Server: The SMTP Server name or IP address. The value is an expression.
  • Server Port: The port number where the connection to the SMTP server must be established. The value is an expression.
  • EnableSSL: Specify if the connection to the SMTP Server must be done using SSL or not. The value is an expression.
  • UserName: The username to use when connecting to the SMTP Server. The value is an expression.
  • Password: The password to use when connecting to the SMTP Server. The value is an expression.
  • From: The e-mail address to use in the 'from' field of the message. The value is an expression.
  • To: The e-mail addresses to use in the 'to' field of the message, separated by comma in case of being more than one. The value is an expression.
  • CC: The e-mail addresses to use in the 'cc' field of the message, separated by comma in case of being more than one. The value is an expression.
  • BCC: The e-mail addresses to use in the 'bcc' field of the message, separated by comma in case of being more than one. The value is an expression.
  • Subject: The subject of the e-mail message. The value is an expression.
  • Body Is HTML: Indicates if the body text is HTML or plain text.
  • Body: The body of the e-mail message. The value is an expression.
  • Priority: The priority of the e-mail message.
  • IgnoreMissingAttachments: True to silently ignore missing attachment files on runtime, False to cause a runtime error when that condition occurs.
  • Attachments: The list of attachments to send with the e-mail message.

When sending attachments, the name of the attachment to send is a constant string value (does not require quotes). Attachment files are set using an expression that returns the path to the file in the 3CX server. In order to create the expression for the attachment file in the server, press the ellipsis button on the last column of the grid.

Launch External Script

Launch External Script configuration

This component allows executing C# code (.NET Core 1.0). You need to specify the object type (namespace and class name), and the method name. The application will create an instance of the specified object and will invoke the specified method on that instance, using the list of parameters provided. The input properties are the following:

  • C# File: The C# file containing the code to execute. Please note that you must use NET Core 1.0 code, and can’t use classes outside NET Core 1.0.
  • ObjectType: The type of the object to create. This is the class name including the namespace.
  • MethodName: The name of the method to execute. An object of type ObjectType will be created and the method will be executed on that object instance.
  • Parameters: A list of parameters used when invoking the method. Each parameter can be an expression. The name of each parameter is informative, and is not used to validate against the method to call.

The C# File is selected from a drop down list, which contains every C# file in the “Libraries” folder of the project. You can browse for the C# file in your file system if it’s not in the list yet.

Parameter names are constant string values and do not require quotes. Parameter values are set using an expression. In order to create an expression for a parameter, press the ellipsis button on the last column of the grid.

The Launch External Script component exposes the following output properties after execution:

  • ReturnValue: contains the value returned by the method called.

Read / Write to File

Read / Write to File configuration

This component allows reading and writing text files.

The reading operation is performed line by line. It is possible to specify the index of the first line to be read (starting at zero), and the quantity of lines to read. It can also be configured to read the entire file at once.

The writing operation allows opening the file in different modes: “Append”, “Create”, “CreateNew”, “Open”, “OpenOrCreate” and “Truncate”.  The “Append” mode will add the text at the end of the file. The “Create” mode will create the file if it does not exist, or truncate it if it already exists, so it always starts with an empty file. The “CreateNew” is very similar but the file must not exist to succeed. The “Open” mode will open the file as it is, and write to it since the beginning, overriding what was on it, while the “OpenOrCreate” is almost the same but if the file doesn’t exist, it creates it. Finally the “Truncate” mode must open an existing file and truncate it. The data to be written is the information in the “Content” property. If the AppendFinalCrLf property is set, Carriage Return and Line Feed characters are added at the end of the line.

This component has the following input properties:

  • FileName: The absolute path to the file to read or write. The value is an expression.
  • OpenMode: Use Append, Create, CreateNew, Open, OpenOrCreate or Truncate when Action is Write. Use Open or OpenOrCreate when Action is Read.
  • Action: The action to perform. It can be Read or Write.
  • Content: The text to write to the file. Only valid when Action is Write. The value is an expression.
  • AppendFinalCrLf: True to append a final CR LF after writing to the file. False otherwise. Only valid when Action is Write.
  • LinesToRead: The number of lines to read from the file. Only valid when Action is Read. The value is an expression.
  • FirstLineToRead: The zero-based index of the first line to read from the file. Only valid when Action is Read. The value is an expression.
  • ReadToEnd: Overrides LinesToRead, reading until the end of file is reached. Only valid when Action is Read. The value is an expression.

The Read / Write to File component exposes the following output properties after execution:

  • EOF_Reached: indicates if the end of the file has been reached when Action is Read.
  • Result: contains the text that has been read from the file when Action is Read.

Open a Socket

Open a Socket configuration

This component allows sending and receiving data using TCP or UDP protocols. You need to specify the destination server and port, along with the information to be sent. If the property WaitForResponse is set, it waits for a response from the server, otherwise it closes the socket immediately after the information is sent. The input properties are the following:

  • ConnectionType: The type of the connection to establish. TCP or UDP.
  • Server Host: The server host name or IP address. The value is an expression.
  • Port: The port number where the server is listening for incoming connections. The value is an expression.
  • Data: The data to send to the server. The value is an expression.
  • WaitForResponse: True to wait for a response after sending the data. False otherwise.

This component exposes the following output properties after execution:

  • Response: contains the server response if the WaitForResponse property was set.

HTTP Requests

HTTP Requests configuration

This component sends HTTP requests to a web server. You can use all the methods available (DELETE, GET, HEAD, OPTIONS, POST, PUT, TRACE). The input properties are the following:

  • URI: The URI where the request must be sent. The value is an expression.
  • RequestType: The type of the HTTP Request. Available values are DELETE, GET, HEAD, OPTIONS, POST, PUT, TRACE.
  • Content-Type: When the HTTP request needs to send content to the server, this property specifies the content type.
  • Content: When the HTTP request needs to send content to the server, this property specifies the actual content. The value is an expression.
  • Timeout: The time to wait for the HTTP request to complete, in seconds. Zero means to wait forever.
  • Headers: A list of headers to send in the request. Each header can be set using an expression. The Header names are constant string values and do not require quotes. The header values are expressions. In order to create an expression for a header value, press the ellipsis button on the last column of the grid.

The HTTP Requests component exposes the following output properties after execution:

  • ResponseStatusCode: contains the HTTP status code returned by the web server. The number 200 (OK) means that the request was processed successfully.
  • ResponseContent: this property contains the response from the web server.

Web Service REST

Web Service REST configuration

This component allows executing REST web services, sending HTTP requests to the server using all the methods available (DELETE, GET, HEAD, OPTIONS, POST, PUT, TRACE), and supporting different types of authentication out of the box. The input properties are the following:

  • URI: The URI where the request must be sent. The value is an expression.
  • RequestType: The type of the HTTP Request. Available values are DELETE, GET, HEAD, OPTIONS, POST, PUT, TRACE.
  • Content-Type: When the HTTP request needs to send content to the server, this property specifies the content type.
  • Content: When the HTTP request needs to send content to the server, this property specifies the actual content. The value is an expression.
  • Timeout: The time to wait for the HTTP request to complete, in seconds. Zero means to wait forever.
  • Authentication: The type of authentication used by the REST web service. You can use:
  • None: to avoid using authentication.
  • Basic - User Name and Password: to use basic authentication providing the user name and a password.
  • Basic - API Key: to use basic authentication providing an API Key.
  • OAuth2: to use OAuth2 providing the Access Token.
  • Headers: A list of headers to send in the request. Each header can be set using an expression. The Header names are constant string values and do not require quotes. The header values are expressions. In order to create an expression for a header value, press the ellipsis button on the last column of the grid.

The Web Service REST component exposes the following output properties after execution:

  • ResponseStatusCode: contains the HTTP status code returned by the web server. The number 200 (OK) means that the request was processed successfully. A response in the range 201-299 has a different success meaning.
  • ResponseContent: this property contains the response from the web server.

Web Service (POST)

Web Service (POST) configuration

This component allows executing web services. It performs a web request using the POST method, to the specified URI and WebServiceName. For example, if the URI is http://www.example.com” and the WebServiceName is “WSName, the component will send the HTTP request to http://www.example.com/WSName. The input properties are the following:

  • URI: The URI where the web service is located. The value is an expression.
  • WebServiceName: The name of the method to invoke. The value is an expression.
  • Content-Type: The content type to send to the server.
  • Content: The content to send to the server. The value is an expression.
  • Timeout: The time to wait for the HTTP request to complete, in seconds. Zero means to wait forever.
  • Headers: A list of headers to send in the request. Each header can be set using an expression.

The Header names are constant string values and do not require quotes. The header values are expressions. In order to create an expression for a header value, press the ellipsis button on the last column of the grid.

The Web Service (POST) component exposes the following output properties after execution:

  • ResponseStatusCode: contains the HTTP status code returned by the web server. The number 200 (OK) means that the request was processed successfully.
  • ResponseContent: contains the response returned by the web service.

User Defined Components

User defined components are automatically added to the toolbox. They can be used to group common functionality, reduce diagram complexity and as a localized error handler or disconnect handler.

Public properties exposed by these components are automatically shown in the Properties window. The user can set an expression to those properties in order to customize the component behaviour.

The component can internally update properties values, so they can be used as component output as well.

See also

Get 3CX Free today

Download On-Premise or Try in the Cloud