Provide a ServiceNow REST API "client" module

[tima]

SUMMARY

The intention of this module is to provide an improved "stopgap" solution for ServiceNow users where a specific module does not exist for a ServiceNow resource including those working with highly customized environments.

ISSUE TYPE

• Feature Idea

COMPONENT NAME

servicenow.itsm.api

ADDITIONAL INFORMATION

This module is like the Ansible core URI module with a thin layer of conveniences to handle common operations like credentials that will always apply to ServiceNow. Without prior knowledge of the data and resource, this module will not have the logic to handle idempotence (desired state).

Consider this example to setup a demo environment where one wants to automate creating a user in ServiceNow:

    - name: create user
      uri:
        url: "{{ instance }}/api/now/table/sys_user?sysparm_input_display_value=true"
        method: POST
        user: "{{ username }}"
        password: "{{ password }}"
        force_basic_auth: true
        headers:
          Content-Type: application/json
        body_format: json
        body:
          user_name: "{{ demo_username }}"
          user_password: "{{ demo_password }}"
          first_name: "{{ first_name }}"
          last_name: Demouser
          department: IT
          email: "{{ demo_username }}@example.com"
          title: instruqt_demo
        status_code: 201
      register: user_create

This proposed module would provide a more concise and straightforward means of performing this task:

    - name: create user
      servicenow.itsm.api:
        resource: sysuser
        action: create
        data:
          user_name: "{{ demo_username }}"
          user_password: "{{ demo_password }}"
          first_name: "{{ first_name }}"
          last_name: Demouser
          department: IT
          email: "{{ demo_username }}@example.com"
          title: instruqt_demo      
        register: user_create   

The proposed module would use the same credential input mechanism as the existing content does today. It default to using JSON for its payloads though YAML is a valid input that will get converted as needed. It would also contain the logic to handle endpoint URI construction, the HTTP method, status code and error handling.

This module would essentially codify the ServiceNow REST API Explorer in an Ansible-native way.

Ideally this module would also include built-in template processing capabilities as an alternative to its data parameter. This is similar to the the template param in the kubernetes.core.k8s module.

    - name: create user
      servicenow.itsm.api:
        resource: sysuser
        action: create
        template: path/to/jinja.tmpl     
        register: user_create   

# contents of jinja.tmpl
user_name: "{{ demo_username }}"
user_password: "{{ demo_password }}"
first_name: "{{ first_name }}"
last_name: Demouser
department: IT
email: "{{ demo_username }}@example.com"
title: instruqt_demo      

[ghost]

Don't have write access to project board, so I can't edit it. This issue has to be moved to "Review in progress" in project board: https://github.com/ansible-collections/servicenow.itsm/projects/1#column-18405803.

[tima]

Should have been closed by PR #201 getting merged.