Ansible / Checklvst Integration
Submitted by Dale on November 11, 2020 - 11:09am
Checklvst, https://checkvist.com, is a web-based list editor (I like its keyboard-driven user experience). Given some of my Ansible playbooks generate to-do lists and Checklvst has an API, I wondered how hard integration could be?
The Ansible uri module made it very easy.
I cleaned up my test code and made a demonstration playbook (below). It's also available as a GitHub gist: https://gist.github.com/dale42/520fa5ad5db2a31c1bce9ce9bb8f97a5
Notes on the playbook:
- The checklvst_credentials variable should come from a vault variable
- The Checklvst Open API page has instructions for getting the Open API key/remote_key
- uri module calls to the Checklvst Open API are delegated to the command node using "delegate_to: localhost"
- Only one access token is needed per playbook so "run_once: true" is used on the task fetching the token (run_once shares the variable among all hosts)
Reference:
- Checklvst Open API documentation: https://checkvist.com/auth/api
- Ansible uri module documentation: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/uri_module.html
For exploring the Checklvst Open API, or any network API, I recommend the Postman app. The download page is https://www.postman.com/downloads/
checklvst-api-demo.yml
#
# Playbook demonstrating Checklvst Open API integration with uri module.
#
# - Checklvst Website: https://checkvist.com
# - Checklvst Open API documentation: https://checkvist.com/auth/api
# - Ansible uri module documentation: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/uri_module.html
#
# To run the playbook update the following variables with your configuration information:
# - host
# - checklvst_credentials.username
# - checklvst_credentials.open_api_key
# - Should be a vault variable
# - Information on getting open_api_key in Checklvst Open API documentation
# - demo_checklist_name
#
---
- name: Checklvst Open API / uri Module Demo
hosts: localhost
gather_facts: no
vars:
checklvst_credentials:
username: YOUR_CHECKLVST_EMAIL_ADDRESS
open_api_key: YOUR_CHECKLVST_OPEN_API_KEY
demo_checklist_name: "YOUR LIST NAME"
display_response: false
tasks:
- name: Get an access token
uri:
url: https://checkvist.com/auth/login.json?version=2
method: POST
body_format: json
body:
username: "{{ checklvst_credentials.username }}"
remote_key: "{{ checklvst_credentials.open_api_key }}"
register: token
delegate_to: localhost
run_once: true
- name: Display the access token response
debug: var=token
when: display_response
- name: Get the list of checklists
uri:
url: https://checkvist.com/checklists.json
method: GET
headers:
X-Client-Token: "{{ token.json.token }}"
register: checklist_response
delegate_to: localhost
run_once: true
- name: Display checklist response
debug: var=checklist_response
when: display_response
- name: Create checklist dictionary
set_fact:
checklist_dict: "{{ checklist_dict | default( {} ) | combine ( { item.name : item.id } ) }}"
loop: "{{ checklist_response.json }}"
loop_control:
label: "{{ item.id }}"
run_once: true
- name: Display the checklist dictionary
debug: var=checklist_dict
run_once: true
- name: Get the Demo List id
set_fact:
demo_checklist_id: "{{ checklist_dict[demo_checklist_name] | default('') }}"
- name: Display demo_checklist_id
debug: var=demo_checklist_id
- name: Fail if checklist id not found
fail:
msg: "Could not find id for checklist: {{ demo_checklist_name }}"
when: demo_checklist_id == ''
- name: Add task
uri:
url: "https://checkvist.com/checklists/{{ demo_checklist_id }}/tasks.json"
method: POST
headers:
X-Client-Token: "{{ token.json.token }}"
body_format: json
body:
task:
content: "New task added from {{ ansible_play_name }} playbook, host {{ inventory_hostname }}"
register: add_task_response
delegate_to: localhost
- name: Display add task response
debug: var=add_task_response
when: display_response
- name: Get task list
uri:
url: "https://checkvist.com/checklists/{{ demo_checklist_id }}/tasks.json"
method: GET
headers:
X-Client-Token: "{{ token.json.token }}"
register: task_list_response
delegate_to: localhost
- name: Display task list response
debug: var=task_list_response
when: display_response
- name: Display task list (json)
debug: var=task_list_response.json