# pubnub_blocks – PubNub blocks management module

- Synopsis

- Requirements

- Parameters

- Examples

- Return Values

- Status

## Synopsis

- This module allows Ansible to interface with the PubNub BLOCKS infrastructure by providing the following operations: create / remove, start / stop and rename for blocks and create / modify / remove for event handlers

## Requirements

The below requirements are needed on the host that executes this module.

- python >= 2.7

- pubnub_blocks_client >= 1.0

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
account - added in 2.4 |  | Name of PubNub account for from which `application` will be used to manage blocks. User's account will be used if value not set or empty.
application - / required |  | Name of target PubNub application for which blocks configuration on specific `keyset` will be done.
cache - | Default: {} | In case if single play use blocks management module few times it is preferred to enabled 'caching' by making previous module to share gathered artifacts and pass them to this parameter.
changes - | Default: {} | List of fields which should be changed by block itself (doesn't affect any event handlers). Possible options for change is: `name`.
description - | Default: "New block" | Short block description which will be later visible on admin.pubnub.com. Used only if block doesn't exists and won't change description for existing block.
email - |  | Email from account for which new session should be started. Not required if `cache` contains result of previous module call (in same play).

event_handlers
-

Default:
[]

List of event handlers which should be updated for specified block `name`.
Each entry for new event handler should contain: `name`, `src`, `channels`, `event`. `name` used as event handler name which can be used later to make changes to it.
`src` is full path to file with event handler code.
`channels` is name of channel from which event handler is waiting for events.
`event` is type of event which is able to trigger event handler: js-before-publish, js-after-publish, js-after-presence.
Each entry for existing handlers should contain `name` (so target handler can be identified). Rest parameters (`src`, `channels` and `event`) can be added if changes required for them.
It is possible to rename event handler by adding `changes` key to event handler payload and pass dictionary, which will contain single key `name`, where new name should be passed.
To remove particular event handler it is possible to set `state` for it to `absent` and it will be removed.

keyset - / required |  | Name of application's keys set which is bound to managed blocks.
name - / required |  | Name of managed block which will be later visible on admin.pubnub.com.
password - |  | Password which match to account to which specified `email` belong. Not required if `cache` contains result of previous module call (in same play).

state
-

Choices:
- started ←
- stopped
- present
- absent

Intended block state after event handlers creation / update process will be completed.

validate_certs
boolean

Choices:
- no
- yes ←

This key allow to try skip certificates check when performing REST API calls. Sometimes host may have issues with certificates on it and this will cause problems to call PubNub REST API.
If check should be ignored `False` should be passed to this parameter.

## Examples

    # Event handler create example.
    - name: Create single event handler
      pubnub_blocks:
        email: '{{ email }}'
        password: '{{ password }}'
        application: '{{ app_name }}'
        keyset: '{{ keyset_name }}'
        name: '{{ block_name }}'
        event_handlers:
          -
            src: '{{ path_to_handler_source }}'
            name: '{{ handler_name }}'
            event: 'js-before-publish'
            channels: '{{ handler_channel }}'

    # Change event handler trigger event type.
    - name: Change event handler 'event'
      pubnub_blocks:
        email: '{{ email }}'
        password: '{{ password }}'
        application: '{{ app_name }}'
        keyset: '{{ keyset_name }}'
        name: '{{ block_name }}'
        event_handlers:
          -
            name: '{{ handler_name }}'
            event: 'js-after-publish'

    # Stop block and event handlers.
    - name: Stopping block
      pubnub_blocks:
        email: '{{ email }}'
        password: '{{ password }}'
        application: '{{ app_name }}'
        keyset: '{{ keyset_name }}'
        name: '{{ block_name }}'
        state: stop

    # Multiple module calls with cached result passing
    - name: Create '{{ block_name }}' block
      register: module_cache
      pubnub_blocks:
        email: '{{ email }}'
        password: '{{ password }}'
        application: '{{ app_name }}'
        keyset: '{{ keyset_name }}'
        name: '{{ block_name }}'
        state: present
    - name: Add '{{ event_handler_1_name }}' handler to '{{ block_name }}'
      register: module_cache
      pubnub_blocks:
        cache: '{{ module_cache }}'
        application: '{{ app_name }}'
        keyset: '{{ keyset_name }}'
        name: '{{ block_name }}'
        state: present
        event_handlers:
          -
            src: '{{ path_to_handler_1_source }}'
            name: '{{ event_handler_1_name }}'
            channels: '{{ event_handler_1_channel }}'
            event: 'js-before-publish'
    - name: Add '{{ event_handler_2_name }}' handler to '{{ block_name }}'
      register: module_cache
      pubnub_blocks:
        cache: '{{ module_cache }}'
        application: '{{ app_name }}'
        keyset: '{{ keyset_name }}'
        name: '{{ block_name }}'
        state: present
        event_handlers:
          -
            src: '{{ path_to_handler_2_source }}'
            name: '{{ event_handler_2_name }}'
            channels: '{{ event_handler_2_channel }}'
            event: 'js-before-publish'
    - name: Start '{{ block_name }}' block
      register: module_cache
      pubnub_blocks:
        cache: '{{ module_cache }}'
        application: '{{ app_name }}'
        keyset: '{{ keyset_name }}'
        name: '{{ block_name }}'
        state: started

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
module_cache dictionary | always | Cached account information. In case if with single play module used few times it is better to pass cached data to next module calls to speed up process.

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- PubNub <support@pubnub.com> (@pubnub)

- Sergey Mamontov <sergey@pubnub.com> (@parfeon)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.