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.