SUBSCRIPTION.PARAMETERS SETTINGS
- Pedro Jose Sanchez Luling
- Josep Benavent
The SUBSCRIPTION.PARAMETERS SETTINGS is a special setting that can be assigned to a PROGRAM.
It allows to define a list of customized parameters that any SUBSCRIPTION to that PROGRAM should have.
For example, when creating a SUBSCRIPTION to a PROGRAM, we can force to include some custom parameters in the SUBSCRIPTION that may change the PROGRAM behavior. Then, when the SUBSCRIPTION is created we can assign values to those parameters that will only take effect on that SUBSCRIPTION.
Example
Let’s suppose that we design a PROGRAM that inserts a TASK that should be performed periodically each N days, but the number of days can be customized for each SUBSCRIPTION.
In this situation we would define the SUBSCRIPTION.PARAMETERS SETTING for the PROGRAM indicating that it is necessary to define a custom parameter called “TASK_FREQUENCY”, which can have a default value.
When a new SUBSCRIPTION is created, we can modify the value of the TASK_FREQUENCY SETTING to the desired number of days for that SUBSCRIPTION.
SUBSCRIPTION.PARAMETERS Format
The SUBSCRIPTION.PARAMETERS is a JSON string composed by an array of items. Each item represents a parameter of the SUBSCRIPTION and has some configuration properties
PROPERTY | DESCRIPTION |
|---|---|
code | An ITEM CODE. This value is mandatory and must be unique |
type | Type of parameter. Defines the type of the value that will be assigned to the parameter. Allowed types are:
|
mandatory | Indicates if it is mandatory to define a value for this parameter when a new SUBSCRIPTION is created |
description | Description of the parameter |
default | Default value that will be assigned when a new SUBSCRIPTION is created |
hidden | (default value = false) If true, the parameter will not be returned by subscription_get () , but it is still visible in the list of SETTINGS of the SUBSCRIPTION (via setting_get_summary () ) |
options | Only for parameters of type “VERTICAL_RADIO”. Defines the list of possible values for the parameter. |
Example
[
{ "code":"freq",
"type":"NUMERICAL",
"description": "Number of days for the periodic task",
"default": 1
"mandatory":false
},
{ "code":"participant_type",
"type":"VERTICAL_RADIO",
"description": "Type of participants",
"mandatory":true,
"options": [
{
"value": "sport",
"description": "Sport event"
},
{
"value": "screening",
"description": "Screening event"
},
]
},
{ "code":"autoadministered",
"type":"BOOLEAN",
"description": "Will the admissions be autoadministered?",
"default": 0,
"hidden": true,
"mandatory":false
}
]Retrieving the value of a SUBSCRIPTION PARAMETER
SUBSCRIPTION PARAMETERS are stored as individual SETTINGS of a SUBSCRIPTION, and the name of the SETTING has the following format:
SUBSCRIPTION.PARAMETER.code
Where code is the code assigned to the parameter when it was defined in the SUBSCRIPTION PARAMETERS of the PROGRAM (see example above).
There are several ways to obtain the values assigned to a SUBSCRIPTION PARAMETER:
setting_get_summary () : Returns a complete list of the SETTINGS of the SUBSCRIPTION, which include the SUBSCRIPTION PARAMETERS
"CONFIGURATION" OBJECT CODE : Use this OBJECT CODE in a FORMULA to retrieve the value of a particular SUBSCRIPTION PARAMETER. For example, to retrieve the value of a parameter named FREQ we would use the following OBJECT CODE:
SUBSCRIPTION.CONFIGURATION{FREQ}