Across all sorts of businesses and business processes, there are tasks that need to be completed on a recurring basis. This is the same task that needs to happen every day, or week or month or year. Some examples could include:
- Weekly test of your website
- Processing payroll payments every 2nd week
- Audit user access to a production environment once a month
- Annual renewal of company domain name
To automate and schedule the creation of issues or tasks within MantisHub, users can check out cron-jobs.org. Cron-jobs.org offer a free service where you can schedule automatic execution of commands or scripts including triggering HTTP calls to any service. It can be used to automatically create reucurring issues within MantisHub to be assigned to your users.
Getting started:
Create/Select a MantisHub User
- Determine a user account in your MantisHub to be the reporter of the recurring issue that will be created by cronjobs. You could create a new user with a meaningful name (e.g. cronjob or scheduler) or select an existing user. This user needs to have access level REPORTER or above for the target projects.
- In your selected/created MantisHub user account, create an API token. You should store a copy of this token as it is only displayed one time, on creation.
Register for cron-jobs.org
- You need to sign up for a cron-jobs account. All you need is a name, email address and password. Head to their website for details.
- Once signed up, you can login by heading to the 'Members' page via the menu at the top of the page and start creating jobs.
Creating a task
- Create a task in cron-job.org and define a schedule.
- Give it a title and set the URL as https://<myinstance>.mantishub.io/api/rest/issues/ (replace <myinstance> with your MantisHub service name).
- Define the schedule (see defining schedules below). Then click 'Create Cronjob'.
- Head back to your Cronjobs list and edit the task. Make the below changes:
- Change HTTP action to POST instead of GET
- Add the following headers:
- Header Name: Authorization, Header Value: <API key created in step 2>
- Header Name: Content-Type, Header Value: application/json
- Request Body – provide a body that is supported by create issue API – see API documentation. The below example provides just minimum information required (summary, description, category and project). There are other fields you can populate via API including assigned user, custom fields, due date, tags etc. See the API documentation for more options.
{ "summary": "This is a recurring issue", "description": "This is a recurring task - description", "category": { "name": "General" }, "project": { "name": "MyProject" } }
- Enable the following check boxes.
- Notifications – check all the boxes.
- Common – check all the boxes
- Save and Test.
Defining Cronjob Schedules
Within your cronjob creation, there are several ways to define. These are shown below.
The first option allows you to set a job every X minutes. It can be as little as 1 minutes or up to every 30mins. This is not likely to be useful for MantisHub task creation but is helpful when testing cronjob setup.
The second and third buttons are for setting up once daily and once monthly tasks respectively. Daily tasks just require you to set the time of day for the cronjob. Monthly tasks need the day of the month as well as time of day.
For other schedules, you would need to use the User defined section. It, unfortunately, doesn't allow you to set a reoccurring period but requires Days of the Month (Date), Day of the week, Months of the year and time of day settings. You can select more than one value in these fields but holding the shift/control/command keys. Here are some examples:
Bi-Weekly:
- Days of Month: Select 1 and 15 (using ctrl/command key)
- Days of the week: Select all
- Months: Select all
- Hours & Minutes: Set your time of day, e.g. 10 and 30 for 10:30am
Quarterly:
- Days of Month: Select 30
- Days of the week: Select all
- Months: Select 3 and 6 and 9 and 12 (using ctrl/command key)
- Hours & Minutes: Set your time of day, e.g. 10 & 30 for 10:30am
Annual:
- Days of Month: Select 1 (or desired day)
- Days of the week: Select all
- Months: Select 1 (for January or desired month)
- Hours & Minutes: Set your time of day, e.g. 10 & 30 for 10:30am
Note that for all above examples we've selected all days of the week. This is because is that if your 'Day of the Month' setting falls on a day of the week that isn't selected, (e.g. 20th is a Saturday & Saturday not selected) the job will not run for that month.
Testing
To test your Cronjob, amend the cronjob schedule to trigger issue creation in the near future. Setting the schedule for every 10 or 15 minutes is a good option. You can check the status of your Cronjob from the Cronjob dashboard. If you see the job has failed, head into your cronjob History to check the results or obtain details on error messages. You can also go into details to get full HTTP header information.
Some errors you might see:
Error | Action |
404 Not Found | check URL |
401 API token needed | Confirm Header has been added for Authorization and the correct token is configured. |
400 Summary (or other fields) not specified | Check your request syntax |
Once issue creation is verified you can reset the schedule.
And that's it! Now you can put your gumboots on and jump in some puddles :-)
Comments