Ansible Collection for ManageEngine ServiceDesk Plus Cloud

The Ansible Collection for ManageEngine ServiceDesk Plus Cloud provides Ansible content that enables users to automate the management of ITSM processes such as requests, problems, changes, and releases.

Description

This collection is ideal for IT administrators, DevOps engineers, and automation specialists who work with ServiceDesk Plus Cloud and want to integrate its capabilities into their infrastructure automation workflows.

Requirements

• Ansible-Core: >= 2.15.0
• Python: >= 3.6
• No additional Python libraries are required.
• A ServiceDesk Plus Cloud instance and OAuth credentials are required for module authentication.

Installation

Before using this collection, you need to install it with the Ansible Galaxy command-line tool:

ansible-galaxy collection install manageengine.sdp_cloud

You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:

collections:
  - name: manageengine.sdp_cloud

To upgrade the collection to the latest available version, run the following command:

ansible-galaxy collection install manageengine.sdp_cloud --upgrade

You can also install a specific version of the collection. Use the following syntax to install version 1.0.0:

ansible-galaxy collection install manageengine.sdp_cloud:==1.0.0

See using Ansible collections for more details.

From Source

1. Clone this repository: bash git clone https://github.com/ManageEngine/manageengine.sdp_cloud.git
2. Navigate to the collection directory: bash cd AnsibleCollections/manageengine/sdp_cloud
3. Build and install the collection: bash ansible-galaxy collection build ansible-galaxy collection install manageengine-sdp_cloud-1.0.0.tar.gz

Use Cases

Here are a few common automation scenarios enabled by this collection:

1. Request Management: Automatically create, update, and query requests during CI/CD pipelines or event-driven automation.
2. Problem Management: Trigger problem records and manage their lifecycle in coordination with incident resolution.
3. Change Management: Automate the creation and update of change requests during system patching or upgrades.
4. Release Management: Automate release planning and deployment tracking.

Modules

Example Usage

Configuration

To securely manage your API credentials, we recommend using a credentials.yml file (excluded from version control) or environment variables.

credentials.yml template:

---
client_id: "YOUR_CLIENT_ID"
client_secret: "YOUR_CLIENT_SECRET"
refresh_token: "YOUR_REFRESH_TOKEN"
dc: "US" # Data Center (US, EU, IN, AU, CN, JP)

Environment Variables (alternative):

You can also set credentials as environment variables. These are used as fallbacks when module parameters are not provided:

• SDP_CLOUD_AUTH_TOKEN - Pre-generated OAuth access token
• SDP_CLOUD_CLIENT_ID - Zoho API Console Client ID
• SDP_CLOUD_CLIENT_SECRET - Zoho API Console Client Secret
• SDP_CLOUD_REFRESH_TOKEN - Long-lived refresh token

export SDP_CLOUD_CLIENT_ID="YOUR_CLIENT_ID"
export SDP_CLOUD_CLIENT_SECRET="YOUR_CLIENT_SECRET"
export SDP_CLOUD_REFRESH_TOKEN="YOUR_REFRESH_TOKEN"

When environment variables are set, you can omit the credential parameters from your playbooks:

- name: Create a Request (credentials from env vars)
  manageengine.sdp_cloud.write_record:
    domain: "sdpondemand.manageengine.com"
    parent_module_name: "request"
    dc: "US"
    portal_name: "ithelpdesk"
    payload:
      subject: "Request created using env var auth"

Playbook Examples

Generate Token:

- name: Fetch OAuth Token
  manageengine.sdp_cloud.oauth_token:
    client_id: "{{ client_id }}"
    client_secret: "{{ client_secret }}"
    refresh_token: "{{ refresh_token }}"
    dc: "{{ dc }}"
  register: auth_token

Get Request Details:

- name: Get Request Details
  manageengine.sdp_cloud.read_record:
    domain: "sdpondemand.manageengine.com"
    parent_module_name: "request"
    parent_id: "100"
    auth_token: "{{ auth_token.access_token }}"
    dc: "{{ dc }}"
    portal_name: "ithelpdesk"

Create a Problem:

- name: Create a Problem
  manageengine.sdp_cloud.write_record:
    auth_token: "{{ auth_token.access_token }}"
    dc: "{{ dc }}"
    domain: "sdpondemand.manageengine.com"
    portal_name: "ithelpdesk"
    parent_module_name: "problem"
    payload:
      title: "Network Latency Issue"
      description: "Users reporting slow access to file server"
      urgency: "High"
      impact: "High"

Update a Problem:

- name: Update a Problem
  manageengine.sdp_cloud.write_record:
    auth_token: "{{ auth_token.access_token }}"
    dc: "{{ dc }}"
    domain: "sdpondemand.manageengine.com"
    portal_name: "ithelpdesk"
    parent_module_name: "problem"
    parent_id: "100"
    payload:
      title: "Updated Title"
      priority: "High"

Create a Release:

- name: Create a Release
  manageengine.sdp_cloud.write_record:
    auth_token: "{{ auth_token.access_token }}"
    dc: "{{ dc }}"
    domain: "sdpondemand.manageengine.com"
    portal_name: "ithelpdesk"
    parent_module_name: "release"
    payload:
      title: "Q3 Application Release"
      description: "Rolling out new features for Q3"
      priority: "Normal"

Delete a Problem:

- name: Delete a Problem
  manageengine.sdp_cloud.write_record:
    auth_token: "{{ auth_token.access_token }}"
    dc: "{{ dc }}"
    domain: "sdpondemand.manageengine.com"
    portal_name: "ithelpdesk"
    parent_module_name: "problem"
    parent_id: "100"
    state: absent

Testing

This collection is tested with: - Ansible-Core >= 2.15.0 - Python 3.9+ - ServiceDesk Plus Cloud

Contributing

We welcome contributions! Please feel free to open an issue or submit a pull request on the repository.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Support

As Red Hat Ansible Certified Content, this collection is entitled to support through the Ansible Automation Platform (AAP) using the Create issue button on the top right corner. If a support case cannot be opened with Red Hat and the collection has been obtained either from Galaxy or GitHub, there may community help available on the Ansible Forum.

You can also contact SDP Cloud support at servicedeskplus-cloud-support@manageengine.com.

Release Notes and Roadmap

For the latest changes, please refer to the Changelogs or GitHub Releases.

Related Information

• ManageEngine ServiceDesk Plus Cloud
• Ansible Collection Documentation

License Information

This collection is licensed under the GNU General Public License v3.0 or later. See: https://www.gnu.org/licenses/gpl-3.0.txt