Executing Context API
Introduction
Scripts and hooks run within a context - either a resource or engine context. A context provides information (e.g. the wallet) for the request to be completed successfully.
The context available to the handler method being called is passed in as the first parameter to the method.
API Methods
:active_wallet
Most hooks and all lifecycle actions are executed in the context of a specific wallet. This wallet is provided through this API method.
The wallet object returned is immutable - i.e. there are no direct
changes that can be made to the wallet without first calling
mutate()
on the wallet.
This approach allows the script to query the wallet without changing data under normal circumstances. Normally only engine methods should be used to change the wallet.
This method has no parameters.
function handler (context)
local wallet = context:active_wallet()
...
end
return ocs.create_lifecycle_action_handler(handler)
This method returns the wallet which is being processed as we’re executing whatever code is able to access this context (e.g. in the context of a hook, if we’re accessing an wallet and that hook gets triggered).
See the wallet documentation for how to use the wallet object returned by this method.
Warning The return value might be nil
if called during the
triggering of an event that is occurring without an wallet (e.g.
pre-get of the related wallet).
:active_lifecycle_instance
When executing a script in the context of a lifecycle (i.e. when the handler is created using the create_lifecycle_action_handler method) the lifecycle being managed is available through this method.
This method has no parameters.
function handler (context)
local lifecycle = context:active_lifecycle_instance()
...
end
return ocs.create_lifecycle_action_handler(handler)
This method returns the lifecycle instance which is
being processed. It will be nil
if the calling code is not being executed in
the context of a lifecycle action.
:active_session
When executing a script in the context of an active rating session (generally as part of a hook), the active session content is available via this method.
This method has no parameters.
function handler (context)
local session = context:active_session()
...
end
return ocs.create_hook_handler(handler)
This method returns the active session which is being
processed. It will be nil
if the calling code is not being executed in
the context of a rating session.
:active_subscription
When executing a script in the context of an active subscription (generally as part of a lifecycle processing event), the active subscription is available via this method.
This method has no parameters.
function handler (context)
local subscription = context:active_subscription()
...
end
return ocs.create_lifecycle_action_handler(handler)
This method returns the subscription which is being
processed. It will be nil
if the calling code is not being executed in
the context of a subscription being processed.
:active_lifecycle_target
When executing a script in the context of a lifecycle (i.e. as part of a lifecycle processing event), the actual object this lifecycle instance is attached to can be accessed by this method.
This method will return the active wallet (if the lifecycle is an wallet lifecycle), the active subscription (if the lifecycle is against a subscription for a service), or a bucket (if the lifecycle is an ancillary lifecycle attached as an annotation to a bucket).
This method has no parameters.
function handler (context)
local target = context:active_lifecycle_target()
if (target.is_wallet())
-- act on the target
else
-- error
end
...
end
return ocs.create_lifecycle_action_handler(handler)
This method returns a lifecycle target object which can then be coerced into the appropriate type of object for further actions. some actions can be taken direct against the lifecycle target itself.
This method can return nil
if the context of the script is not within
lifecycle processing.
:active_document
When executing a script in the context of the resource endpoint (i.e. the
/resource/
API endpoint) hook, the active JSON document that is being
processed is available via the active_document()
method.
This method returns the active OCS document which then may be used to retrieve the raw Java JSON object (specifically a Vert.X JsonObject as a mutable object. Any changes to the JSON object may impact the document returned to the client, or stored into the database (the exact use case depends on the point at which the script is being run).
This method has no parameters.
function handler (context)
local doc = context:active_document()
...
end
return ocs.create_hook_handler(handler)
This method returns the document object when the script is run in the
context of a call to the resource
endpoint of the OCS API. Otherwise
it will return nil
.
:ancillary_information
Often a situation will require additional contextual information. This might include data from a service instance during subscription processing, or data added to a charging request either before or after a the charging session executes.
The ancillary_information()
method returns this information as a table
of Lua data.
:engine_request
When executing a script in the context of the OCS engine, the request the
engine is processing can be retrieved by calling the engine_request()
method. The returned table of data represents the information provided by the
client when triggering the OCS.
This method has no parameters.
function handler (context)
local request = context:engine_request()
...
end
return ocs.create_hook_handler(handler)
This method returns a engine request table.
If the Lua code is not being called in the context of the engine (i.e. this
is a resource hook), this will return nil
.
:engine_response
When executing a script in the context of the OCS engine, the response currently
being sent back to the client process that triggered this request is available
by calling this engine_response()
method.
Unlike the engine_request()
the engine response represents a living object
which can be manipulated.
This method has no parameters.
function handler (context)
local response = context:engine_response()
...
end
return ocs.create_hook_handler(handler)
This method returns a engine response object.
If the Lua code is not being called in the context of the engine (i.e. this
is a resource hook), this will return nil
.