Modules
=======

While different modules perform different tasks, their interfaces all follow
the same pattern as much as possible.

The API of each module is composed of two parts. Information iside the
*instance* parameter influences how moddules connect to the ServiceNow
instance. All other parameters hold the information related to the resource
that we are operating on.


Instance parameters
-------------------

Each module has an *instance* parameter that holds the following information
about the ServiceNow instance process we would like to manage:

 1. Instance address, e.g. `https://dev12345.service-now.com/`.
 2. Username and password that Ansible modules should use to authenticate with
    the ServiceNow instance.
 3. The optional client id and secret that indicate modules should use OAuth
    when authenticating.

.. code-block:: yaml

   - name: Create a new incident
     servicenow.itsm.incident:
       instance:
         host: https://dev12345.service-now.com
         username: user
         password: pass
         client_id: cid
         client_secret: csecret
       # Other incident parameters here


Managing ServiceNow records
---------------------------------

There are two things modules from the ServiceNow Ansible Collection can do:

1. Enforce certain state of the records (creating, updating, and deleting
   incidents, change requests, etc.).
2. List and filter available records.

Reference material for each module contains documentation on what parameters
certain modules accept and what values they expect those parameters to be.


Module reference
----------------

.. toctree::
   :glob:
   :maxdepth: 1

   modules/*