# Writing a new Ansible FreeIPA module

## Minimum requirements

A ansible-freeipa module should have:

* Code:

  * A module file placed in `plugins/modules/<ipa_module_name>.py`

* Documentation:

  * `README-<module_name>.md` file in the root directory and linked from the main README.md

  * Example playbooks in `playbooks/<module_name>/` directory

* Tests:

  * Test cases (also playbooks) defined in `tests/<module_name>/test_<something>.yml`. It's ok to have multiple files in this directory.

## Code

The module file have to start with the python shebang line, license header and definition of the constants `ANSIBLE_METADATA`, `DOCUMENTATION`, `EXAMPLES` and `RETURNS`. Those constants need to be defined before the code (even imports). See https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#starting-a-new-module for more information.

Although it's use is not yet required, ansible-freeipa provides `FreeIPABaseModule` as a helper class for the implementation of new modules. See the example bellow:

```python

from ansible.module_utils.ansible_freeipa_module import FreeIPABaseModule

class SomeIPAModule(FreeIPABaseModule):

    ipa_param_mapping = {

        "arg_to_be_passed_to_ipa_command": "module_param",

        "another_arg": "get_another_module_param",

    }

    def get_another_module_param(self):

        another_module_param = self.ipa_params.another_module_param

        # Validate or modify another_module_param ...

        return another_module_param

    def check_ipa_params(self):

        # Validate your params here ...

        # Example:

        if not self.ipa_params.module_param in VALID_OPTIONS:

            self.fail_json(msg="Invalid value for argument module_param")

    def define_ipa_commands(self):

        args = self.get_ipa_command_args()

        self.add_ipa_command("some_ipa_command", name="obj-name", args=args)

def main():

    ipa_module = SomeIPAModule(argument_spec=dict(

        module_param=dict(type="str", default=None, required=False),

        another_module_param=dict(type="str", default=None, required=False),

    ))

    ipa_module.ipa_run()

if __name__ == "__main__":

    main()

```

In the example above, the module will call the command `some_ipa_command`, using "obj-name" as name and, `arg_to_be_passed_to_ipa_command` and `another_arg` as arguments.

The values of the arguments will be determined by the class attribute `ipa_param_mapping`.

In the case of `arg_to_be_passed_to_ipa_command` the key (`module_param`) is defined in the module `argument_specs` so the value of the argument is actually used.

On the other hand, `another_arg` as mapped to something else: a callable method. In this case the method will be called and it's result used as value for `another_arg`.

**NOTE**: Keep mind that to take advantage of the parameters mapping defined in `ipa_param_mapping` you will have to call `args = self.get_ipa_command_args()` and use `args` in your command. There is no implicit call of this method.

## Disclaimer

The `FreeIPABaseModule` is new and might not be suitable to all cases and every module yet. In case you need to extend it's functionality for a new module please open an issue or PR and we'll be happy to discuss it.