Event Scripting
(→Creating/Updating an Event Script) |
(→Queued (>= 2.3.0)) |
||
(9 intermediate revisions by 2 users not shown) | |||
Line 6: | Line 6: | ||
* '''resource''' is the optional resource path ('/' replaced with '.') either statically defined, or using replacement parameters within {}, i.e. db._table.{table_name}.get.pre_process, | * '''resource''' is the optional resource path ('/' replaced with '.') either statically defined, or using replacement parameters within {}, i.e. db._table.{table_name}.get.pre_process, | ||
* '''verb''' is the HTTP verb used in the request | * '''verb''' is the HTTP verb used in the request | ||
− | * '''type''' is the type of event, see below | + | * '''type''' is the type of event, see below |
− | + | ||
==Scriptable Event Types== | ==Scriptable Event Types== | ||
− | Scriptable events currently fall under three categories: pre-process, post-process, and queued. The pre- and post-process types affect processing of the API call, being run between the time the server receives the call and the response to the client. '''Note''': Care must be taken as the time to process the script itself affects the response time to the client. | + | Scriptable events currently fall under three categories: pre-process, post-process, and queued. The pre- and post-process types affect processing of the API call, being run between the time the server receives the call and the response to the client. '''Note''': Care must be taken as the time to process the script itself affects the response time to the client. The queued scripts are queued during the API call, and processed at a later time. |
===Pre-Process=== | ===Pre-Process=== | ||
Line 22: | Line 22: | ||
* perform additional functionality before the response is returned to the client, i.e. triggering other services upon success or failure, logging, etc. | * perform additional functionality before the response is returned to the client, i.e. triggering other services upon success or failure, logging, etc. | ||
− | ===Queued | + | ===Queued=== |
− | + | Starting with release 2.3.0, queued scripts, on the other hand, do not and cannot affect the processing of the original API call. Both the request and response of the event are saved along with the script and queued for later execution. Queued scripts are primarily useful for triggering other workflows that need to be done when an event happens, but not necessarily during the processing of the event. | |
==Event Script Configuration== | ==Event Script Configuration== | ||
− | + | Release 2.3.0 changed how the events and associated scripts are managed in the API see the sub-sections before for the old calls. | |
+ | |||
===Retrieving a List of Events=== | ===Retrieving a List of Events=== | ||
− | To retrieve a list of events that can be scripted, issue a GET on the following API endpoint. Use the '''service''' filter the output. Adding the '''as_list''' parameter set to true returns just the list of names. | + | To retrieve a list of events that can be scripted, issue a GET on the following API endpoint. Use the '''service''' parameter to filter the output. Adding the '''as_list''' parameter set to true returns just the list of names. This API endpoint returns the events of the system, adding '''scriptable''' set to true will return the full event names with the script type on the end. |
+ | <pre>http://example.com/api/v2/system/event?scriptable=true[&service=<service_name>][&as_list=true]</pre> | ||
+ | |||
+ | ====Before 2.3.0==== | ||
<pre>http://example.com/api/v2/system/event?type=process[&service=<service_name>][&as_list=true]</pre> | <pre>http://example.com/api/v2/system/event?type=process[&service=<service_name>][&as_list=true]</pre> | ||
===Retrieving a List of Scripted Events=== | ===Retrieving a List of Scripted Events=== | ||
− | To retrieve a list of events that already have associated scripts, issue a GET on the | + | To retrieve a list of events that already have associated scripts, issue a GET on the event_script API endpoint |
+ | <pre>http://example.com/api/v2/system/event_script?[as_list=true]</pre> | ||
+ | |||
+ | ====Before 2.3.0==== | ||
+ | To retrieve a list of events that already have associated scripts, issue a GET on the event API endpoint but add the '''only_scripted''' set to true | ||
<pre>http://example.com/api/v2/system/event?type=process&only_scripted=true[&service=<service_name>][&as_list=true]</pre> | <pre>http://example.com/api/v2/system/event?type=process&only_scripted=true[&service=<service_name>][&as_list=true]</pre> | ||
===Retrieving Details of an Event Script=== | ===Retrieving Details of an Event Script=== | ||
− | Select an event by '''name''' to retrieve a list of its details including content of the script itself, by issuing a GET on the following API endpoint. Use the '''fields''' URL parameter to select specific fields to return, '*' by default. | + | Select an event by '''name''' to retrieve a list of its details including content of the script itself, by issuing a GET on the following API endpoint. Use the '''fields''' URL parameter to select specific fields to return, '*' returns all by default. |
+ | <pre>http://example.com/api/v2/system/event_script/{event_name}[?fields=<field1,field2>]</pre> | ||
+ | |||
+ | ====Before 2.3.0==== | ||
<pre>http://example.com/api/v2/system/event/{event_name}[?fields=<field1,field2>]</pre> | <pre>http://example.com/api/v2/system/event/{event_name}[?fields=<field1,field2>]</pre> | ||
+ | |||
+ | The response would resemble the following... | ||
+ | <source lang="javascript"> | ||
+ | { | ||
+ | "name": "event_name", | ||
+ | "type": "string", | ||
+ | "is_active": true, | ||
+ | "content": "string", | ||
+ | "config": "string", | ||
+ | "allow_event_modification": true | ||
+ | } | ||
+ | </source> | ||
===Creating/Updating an Event Script=== | ===Creating/Updating an Event Script=== | ||
− | Configuring an event script | + | Configuring an event script consists of the following steps: |
* Select an event by '''name'''. See above for retrieving scriptable event names. | * Select an event by '''name'''. See above for retrieving scriptable event names. | ||
* Select the language '''type''' you wish to write the script in. See [[DreamFactory/Features/Scripting#Supported_Scripting_Languages]]. | * Select the language '''type''' you wish to write the script in. See [[DreamFactory/Features/Scripting#Supported_Scripting_Languages]]. | ||
* Enable the script to run when the event fires by setting the '''is_active''' boolean to true; false to disable. | * Enable the script to run when the event fires by setting the '''is_active''' boolean to true; false to disable. | ||
* Allow the script to modify the event structure (pre- and post-processing only) by setting '''allow_event_modification''' to true; false to disable. | * Allow the script to modify the event structure (pre- and post-processing only) by setting '''allow_event_modification''' to true; false to disable. | ||
− | * Write the '''content''' or body of your script. '''Note''': This | + | * Write the '''content''' or body of your script. '''Note''': This needs to be stringified to pass as content in the payload. |
− | + | ||
+ | POST the below format to the following API endpoint. | ||
+ | <pre>http://example.com/api/v2/system/event_script/{event_name}</pre> | ||
+ | ====Before 2.3.0==== | ||
<pre>http://example.com/api/v2/system/event/{event_name}</pre> | <pre>http://example.com/api/v2/system/event/{event_name}</pre> | ||
+ | |||
<source lang="javascript"> | <source lang="javascript"> | ||
{ | { | ||
"type": "string", | "type": "string", | ||
"is_active": true, | "is_active": true, | ||
− | |||
"content": "string", | "content": "string", | ||
"config": "string", | "config": "string", | ||
Line 61: | Line 87: | ||
==Event Examples== | ==Event Examples== | ||
Below are some example base event names (not including the '''type''' section) for various service types. | Below are some example base event names (not including the '''type''' section) for various service types. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | * [[DreamFactory/Features/Database#Events|Database Services]] | |
− | + | * [[DreamFactory/Features/Files#Events|File Storage Services]] | |
− | + | * [[DreamFactory/Features/HTTP_Services#Events|HTTP Services]] | |
+ | * [[DreamFactory/Features/SOAP_Services#Events|SOAP Services]] | ||
===Auth Services=== | ===Auth Services=== |
Latest revision as of 22:25, 21 November 2016
Event Scripting allows users to write scripts that run when certain system events happen. Scriptable events, a.k.a process events, are "fired" when certain parts of the API are called, externally by clients, or internally by other scripts. Events are generated for all services and most resources defined by those services.
Event Format
API-generated events typically take the form ofservice[.resource].verb[.type]where
- service is the API name of the service,
- resource is the optional resource path ('/' replaced with '.') either statically defined, or using replacement parameters within {}, i.e. db._table.{table_name}.get.pre_process,
- verb is the HTTP verb used in the request
- type is the type of event, see below
Scriptable Event Types
Scriptable events currently fall under three categories: pre-process, post-process, and queued. The pre- and post-process types affect processing of the API call, being run between the time the server receives the call and the response to the client. Note: Care must be taken as the time to process the script itself affects the response time to the client. The queued scripts are queued during the API call, and processed at a later time.
Pre-Process
Following the anatomy of an API call, pre-process scripts are run after authentication and authorization, but before the API call is processed by to the handling service. This allows for the following scenarios...
- interrupting the API call before it is processed by throwing exceptions that are returned to the client, i.e. payload validation failures, etc.,
- modifying the contents, parameters, or headers of the request to change how and/or what is processed, i.e. payload modification, etc. (see allow_event_modification in DreamFactory/Features/Scripting#Resources_Available_To_A_Script)
- perform additional functionality before the call is processed, i.e. external validation, tracking API usage, etc.
Post-Process
Likewise, post-process scripts are run after the API call has been processed by the handling service, but before any final formatting and returning to the client. This allows for the following scenarios...
- modifying the contents, status code, or formatting of the response, i.e. adding related data from other services, or removing sensitive information, etc. (see allow_event_modification in DreamFactory/Features/Scripting#Resources_Available_To_A_Script)
- perform additional functionality before the response is returned to the client, i.e. triggering other services upon success or failure, logging, etc.
Queued
Starting with release 2.3.0, queued scripts, on the other hand, do not and cannot affect the processing of the original API call. Both the request and response of the event are saved along with the script and queued for later execution. Queued scripts are primarily useful for triggering other workflows that need to be done when an event happens, but not necessarily during the processing of the event.
Event Script Configuration
Release 2.3.0 changed how the events and associated scripts are managed in the API see the sub-sections before for the old calls.
Retrieving a List of Events
To retrieve a list of events that can be scripted, issue a GET on the following API endpoint. Use the service parameter to filter the output. Adding the as_list parameter set to true returns just the list of names. This API endpoint returns the events of the system, adding scriptable set to true will return the full event names with the script type on the end.
http://example.com/api/v2/system/event?scriptable=true[&service=<service_name>][&as_list=true]
Before 2.3.0
http://example.com/api/v2/system/event?type=process[&service=<service_name>][&as_list=true]
Retrieving a List of Scripted Events
To retrieve a list of events that already have associated scripts, issue a GET on the event_script API endpoint
http://example.com/api/v2/system/event_script?[as_list=true]
Before 2.3.0
To retrieve a list of events that already have associated scripts, issue a GET on the event API endpoint but add the only_scripted set to true
http://example.com/api/v2/system/event?type=process&only_scripted=true[&service=<service_name>][&as_list=true]
Retrieving Details of an Event Script
Select an event by name to retrieve a list of its details including content of the script itself, by issuing a GET on the following API endpoint. Use the fields URL parameter to select specific fields to return, '*' returns all by default.
http://example.com/api/v2/system/event_script/{event_name}[?fields=<field1,field2>]
Before 2.3.0
http://example.com/api/v2/system/event/{event_name}[?fields=<field1,field2>]
The response would resemble the following...
{ "name": "event_name", "type": "string", "is_active": true, "content": "string", "config": "string", "allow_event_modification": true }
Creating/Updating an Event Script
Configuring an event script consists of the following steps:
- Select an event by name. See above for retrieving scriptable event names.
- Select the language type you wish to write the script in. See DreamFactory/Features/Scripting#Supported_Scripting_Languages.
- Enable the script to run when the event fires by setting the is_active boolean to true; false to disable.
- Allow the script to modify the event structure (pre- and post-processing only) by setting allow_event_modification to true; false to disable.
- Write the content or body of your script. Note: This needs to be stringified to pass as content in the payload.
POST the below format to the following API endpoint.
http://example.com/api/v2/system/event_script/{event_name}
Before 2.3.0
http://example.com/api/v2/system/event/{event_name}
{ "type": "string", "is_active": true, "content": "string", "config": "string", "allow_event_modification": true }
Event Examples
Below are some example base event names (not including the type section) for various service types.
Auth Services
- user.get,
- user.password.post,
- user.profile.get,
- user.profile.post,
- user.register.post,
- user.session.get,
- user.session.post,
- user.session.delete,
- user.custom.get,
- user.custom.post,
- user.custom.patch,
- user.custom.delete,
- user.custom.{id}.get,
- user.custom.{id}.patch,
- user.custom.{id}.delete,
System Resources
The system service generates a lot of events, for example, for the root retrieval of resources...
- system.get
for common resources like admin, app, app_group, custom, cors, roles, services, users...
- system.service.get,
- system.service.post,
- system.service.patch,
- system.service.delete,
- system.service.{id}.get,
- system.service.{id}.patch,
- system.service.{id}.delete,
some others include...
- system.cache.delete,
- system.cache.{service}.delete,
- system.config.get,
- system.config.post,
- system.constant.get,
- system.constant.{type}.get,
- system.environment.get,
- system.event.get,
- system.event.{event_name}.get,
- system.event.{event_name}.post,
- system.event.{event_name}.delete,
- system.service_type.get,
- system.script_type.get,
- system.package.get,
- system.package.post,