General information about setting up your Python environment, testing modules, Ansible coding styles, and more can be found in the Ansible Community Guide.
The Ansible Collection for ServiceNow IT Service Management (ITSM) includes a variety of Ansible content to help automate the management of ServiceNow IT Service Management.
New modules and plugins developed by the community should be proposed to servicenow.itsm.
All software has bugs, and the servicenow.itsm collection is no exception. When you find a bug,
you can help tremendously by telling us about it.
If you should discover that the bug you're trying to file already exists in an issue, you can help by verifying the behavior of the reported bug with a comment in that issue, or by reporting any additional information.
- Sign up for a ServiceNow ID
- Request and setup an Instance.
- When the instance is ready, you will be redirected to the Developer Portal, for example
https://dev12345.service-now.com/. In All, search forApplication Registrythen New - Create an OAuth API endpoint for external clients. - Ensure that you have changed the Integration tests configuration file accordingly with your Personal Developer Instance credentials for the connection and access. A template is available here.
- For more information, check General usage patterns.
- If you are running unit tests or integration tests included in
servicenow.itsmsource usingmakecommand, it is advised to installed container runtimes such as Podman or Docker. For more information please refer Ansible Testing Guidelines.
New modules and plugins should be submitted to the servicenow.itsm collection.
For new features and bug fixes on existing modules and plugins, clone this repository and try to run unit tests and integration tests by following these instructions. When you get to this part, we use a wide variety of linters and static code analysis tools to ensure our code base stays healthy. To run all checks, we can execute the following command:
(venv) $ make sanity
This command will take care of installing requirements and running them.
We use unit tests to test the logic and implementation of our helper functions and various Ansible plugins that are part of the servicenow.itsm collection.
(venv) $ make units
(venv) $ make integration
With the help of integration tests, we make sure that the plugins from the ServiceNow Ansible Collection work as expected when we run them against a ServiceNow instance. We use ansible-test integration, which executes our test targets (roles) that contain test playbooks. More information regarding integration tests can be found here.
Expected test criteria:
- Resource creation under check mode
- Resource creation
- Resource creation again (idempotency) under check mode
- Resource creation again (idempotency)
- Resource modification under check mode
- Resource modification
- Resource modification again (idempotency) under check mode
- Resource modification again (idempotency)
- Resource deletion under check mode
- Resource deletion
- Resource deletion (of a non-existent resource) under check mode
- Resource deletion (of a non-existent resource)
Where modules and plugins have multiple parameters we recommend running through the 4-step modification cycle for each parameter the module accepts, as well as a modification cycle where as most, if not all, parameters are modified at the same time.
For general information on running the integration tests see the Integration Tests page of the Module Development Guide. For questions about writing tests the Ansible ServiceNow ITSM can be found on Libera.Chat IRC as detailed below.
The servicenow.itsm collection follows the Ansible project's
Code of Conduct.
Please read and familiarize yourself with this document.
Our IRC channels may require you to register your nickname. If you receive an error when you connect, see Libera.Chat's Nickname Registration guide for instructions.
The #ansible-community channel on libera.chat IRC is the main and official place to discuss the use and development of the serviceNow.itsm collection.