Bots are virtual Pyrus users that can be directed to perform tasks or approve forms. Each bot has an associated program (a web service) that performs a specific function. When a task or form is routed to the bot, Pyrus invokes a call to the web service. The bot performs its action and then returns the result to Pyrus. Pyrus stores the results in comment or form fields and forwards the task to the next workflow stage (or returns it to a previous stage).
Bots help when you need to address a workflow task or ensure integration with your company’s internal systems. Possible scenarios include:
The bot plays whatever part of the workflow you program it to. In this case, it is important to take two limitations into account:
A bot is a special type of Pyrus account. You can create one from the Bots tab in User Management. A company can create up to 100 bots. The number of bot calls is limited: you can make 500 calls per 10 minutes. A bot account’s payment terms are identical to those of a regular employee account.
Each bot is given a name to serve as a unique identifier, like bot@892ccfa1c8360e2e8309. You cannot log into the system through a web interface or mobile app using this login name; it merely lets you to get a token and call the Pyrus API using the bot’s credentials.
You need to develop a handler app for each bot, and host these apps on your server. When a task is delivered to a bot’s Inbox, it sends a request to the event handler.
Here is an example of bot code written in Python.
import hmac import hashlib import json from flask import Flask from flask import request app = Flask(__name__) @app.route("/", methods=['GET', 'POST']) def index(): body = request.data signature = request.headers['x-pyrus-sig'] secret = 'This-is-bot-secret-key-VtBOEesdOnIcqGaWQeFkWFqyzgdt2PGsZVWBc8h8H0-xU9ux-dN37IjcAqf2pzeqoo5FqdtoH' if _is_signature_correct(body, secret, signature): return _prepare_response(body.decode('utf-8')) def _is_signature_correct(message, secret, signature): secret = str.encode(secret) digest = hmac.new(secret, msg=message, digestmod=hashlib.sha1).hexdigest() return hmac.compare_digest(digest, signature.lower()) def _prepare_response(body): task = json.loads(body)["task"] task_author = task["author"]["email"] return "{{\"text\": \"Hello, {}. This task approved by bot.\", \"approval_choice\": \"approved\"}}".format(task_author) if __name__ == "__main__": app.run("127.0.0.1", 5001) # !!!Do not forget to replace the address!!!
Pyrus uses the POST method to send an HTTPS request to your bot. Your bot must respond to the request with the 2XX status within 60 seconds of this call. If the bot server is unavailable or responds with any other status, Pyrus sends a second request in 61 seconds and a third one in 122 seconds. You can see the number of attempts in X-Pyrus-Retry, the additional header of the request. If Pyrus fails to communicate within three attempts, it will stop trying to call the bot until someone comments on the task. Then Pyrus will carry out another three attempts.
To create and configure bots, you need to have the right to configuration integrations and edit catalogs in Pyrus.