Add module to create requests via service catalog

[minsis]

SUMMARY

For the most part you can't really add records to sc_req and and sc_req_item tables without having the internal role, which you can't assign publicly anyways. It would be good to have a module that could create orders from the service catalog.

Since servicenow.itsm.api doesn't support anything outside of /now/table calls there's no good way to utilize this collection. #247 is asking to allow calls outside of /now/table, but since making a call to the service catalog api, there's a whole host of things that can be configured, so it might be better to have it as its own module.

ISSUE TYPE

• Feature Idea

COMPONENT NAME

Having a module servicenow.itsm.service_catalog that would essentially making calls to the /sn_sc/servicecatalog/ API endpoint.

ADDITIONAL INFORMATION

- name: "Order my item"
  servicenow.itsm.service_catalog
    template: "{{ catalog_sys_id }}"
    data:
      short_description: "I need this thing"
      description: "I need this thing now!"
      vairable1: "variable1"
      vairable2: "variable2"

This is just an example of a use case for a single order to submit to api/sn_sc/servicecatalog/items/{sys_id}/order_now, but other actions might be a good thing to, like adding to cart, checkout, etc.

Currently I just use raw api, but it would be nice to utilize this collection since its all servicenow related, and features of this collection (like setting environment variables for username/password)

My current workaround:

- name: "Build the request payload"
  ansible.builtin.set_fact:
    payload:
      variables:
        select_activity: "<The select_activity field>"
        description: "<description field>"
        short_description: "<short_description field>"
      sysparm_quantity: 1

- name: "Create request via Service Catalog"
  ansible.builtin.uri:
    url: "{{ sn_endpoint }}/api/sn_sc/servicecatalog/items/{{ catalog_sys_id }}/order_now"
    user: "{{ sn_user }}"
    password: "{{ sn_pass }}"
    method: "POST"
    body: "{{ payload | to_json }}"
    body_format: json
    headers: "{{ headers }}"
    return_content: true
  register: request

- name: "Request Created"
  debug:
    msg: "Request {{ request.json.result.number }} Created"

[mhjacks]

Hi @minsis - Thanks for the idea. What additional value do you think providing a separate module could provide? I agree completely that doing this through builtin.uri is suboptimal (though possible, as you've demonstrated). The "normal" path we'd expect users to follow is to use the generic API module now (as of 2.4.0). Is there something you see a separate module enabling that wouldn't be possible via the API module?

[vasiredp]

May i know is this module available now to use for service catalogue ?

[mhjacks]

It's in the main branch now, but not yet in a released version. It will be released in version 2.5.0.

[minsis]

Sorry for the delays I keep forgetting to reply.

Seems this is now being applied in some way but I'll still answer just to cover the question.

Basically, the value it brings is just like any of the other modules: ease of use and simplicity for the end user. It also brings more functionality to the collection when accounts are limited in usage. Since creating a record on the sc_req and sc_req_item table are limited to the internal role it makes it difficult to create requests like this. For example, we have automation that creates tickets for user account actions and those are done via the SC and have the built-in approvals and flows associated with that request.

I think it would be fine just using servicenow.itsm.api module to do this, but as of my OP the module didn't support that. At the time the module only supported specifying a resource table and then setting the endpoint to /now/table

[minsis]

Also to expand it would add ease of use and tracking for building a cart as well. So, in my same example, we could create a cart of the different account types we have and then do a final checkout. With a standard module the user will have the exact known return values needed vs using the generic api module which you need to know what data your api is going to return.

[mhjacks]

@minsis I completely get that. This issue was one of the reasons we added a more generic API function. We don't want people to have to worry about things like Authorization headers to do this. At the same time, there are a lot of ServiceNow APIs and it's daunting for us to try to track changes to every one of them. We were absolutely planning for this exact sort of thing to be possible with the changes to the api and api_info modules. This is sort of a test case to see whether that's enough, or whether we need to do something more.

Meanwhile, is it feasible for you to test with the main branch prior to the 2.5.0 release (which depends on some things, but I'd guess is weeks and certainly not months away)?

[minsis]

@mhjacks You're wanting me to test the changes to api module using the api/sn_sc/servicecatalog/items/{sys_id}/order_now endpoint?

[mhjacks]

@minsis Yes, if you're willing and able.

[minsis]

@mhjacks I was able to test with the following:

- hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: "Create Service Catalog Ticket"
      servicenow.itsm.api:
        action: "post"
        api_path: "api/sn_sc/servicecatalog/items/{{ lookup('ansible.builtin.env', 'SYSID') }}/order_now"
        data:
          sysparm_quantity: 1
          variables:
            requested_for: "<redacted>"
            requested_for_manager: "<redacted>"
            request_type: "Add Account"
            short_description: "Add user 1"
            description: "Need to create an account for user 1"
            email_address_hos: "<redacted>"

{
    "changed": true,
    "diff": {
        "after": {
            "number": "<redacted>",
            "parent_id": null,
            "parent_table": "task",
            "request_id": "<redacted>",
            "request_number": "<redacted>",
            "sys_id": "<redacted>",
            "table": "sc_request"
        },
        "before": null
    },
    "invocation": {
        "module_args": {
            "action": "post",
            "api_path": "api/sn_sc/servicecatalog/items/<redacted>/order_now",
            "data": {
                "sysparm_quantity": 1,
                "variables": {
                    "description": "Need to create an account for user 1",
                    "email_address_hos": "<redacted>",
                    "request_type": "Add Account",
                    "requested_for": "<redacted>",
                    "requested_for_manager": "<redacted>",
                    "short_description": "Add user 1"
                }
            },
            "instance": {
                "access_token": null,
                "api_path": "api/now",
                "client_id": null,
                "client_secret": null,
                "custom_headers": null,
                "grant_type": null,
                "host": "<redacted>",
                "password": "VALUE_SPECIFIED_IN_NO_LOG_PARAMETER",
                "refresh_token": null,
                "timeout": null,
                "username": "<redacted>",
                "validate_certs": true
            },
            "query_params": {},
            "resource": null,
            "sys_id": null,
            "template": null
        }
    },
    "record": {
        "number": "<redacted>",
        "parent_id": null,
        "parent_table": "task",
        "request_id": "<redacted>",
        "request_number": "<redacted>",
        "sys_id": "<redacted>",
        "table": "sc_request"
    }
}

However, there is some confusion as you can see in the output as well as the documentation. The newly added instance.api_path does not apply on this module and the module in fact has its own separate api_path attribute. The documentation for this module doesn't align with this.

Obviously the module is ignoring instance.api_path but I question why it was added to instance and to the module.

[mhjacks]

@tupyy Could you please take a look?

[mhjacks]

@minsis Thanks for trying this out. We'll investigate further

[tupyy]

Hello,
instance.api_path needs to be removed because it's not used anymore. Before 2.4.0, the base_path was hardcoded into the rest client because the modules targeted only api/now endpoints and modules provided only the rest of the path.
Now, api.api_path field is a complete path of the endpoint therefore the instance.api_path is not used anymore

[tupyy]

@minsis Modules for service_catalog are available in the latest release 2.6.0.
Please take a look and if something is missing or there's a bug, please open an issue.