Forms
Forms are a set of fields and routing rules that describe a business process.
A typical example here is reimbursing an employee for travel expenses.
Form fields are a data set that each business process participant works with.
The travel reimbursement business process may include form fields for an employee's last name, the date of the trip, the total reimbursement request, and receipts.
The workflow Is a set of rules that describe how a task moves throughout its business process. Workflows are usually divided into steps. Each step can be given a name, and you can configure rules for automatically adding participants at relevant steps.
For example, the “Travel expense reimbursement” workflow can be divided into the following steps:
"Fill". At this step, the author of the task fills out all the required fields and attaches the supporting documents.
"Approval". At this step, you can add different users to the task, depending on the amount requested.
"Accounting". At this step, the accountant reimburses the employee for the expenses.
You can find additional information about forms in the help section.
Methods
- GET/formsGet all form templates
- GET/forms/{form-id}Get form template
- GET/forms/{form-id}/registerGet list of tasks based on form template
- GET/forms/{form-id}/permissionsGet list of user permissions for the form
- POST/forms/{form_id}/permissionsChange a user’s access rights
GET /forms
This method returns a description of all the forms in which the current user is a manager or a member.
GET https://api.pyrus.com/v4/forms
Response body
{
"forms": [
{
"id": 36120,
"name": "Payments",
"steps": {
"1": "Manager",
"2": "Accounting",
"4": "CEO"
},
"fields": [
{
"id": 1,
"type": "text",
"name": "Purpose",
"info": {
"required_step": 1,
"immutable_step": 1
}
},
{
"id": 2,
"type": "money",
"name": "Amount",
},
{
"id": 3,
"type": "catalog",
"name": "Payment type",
"info": {
"catalog_id": 277
}
},
{
"id": 4,
"type": "table",
"name": "Payment Schedule",
"info": {
"columns": [
{
"id": 5,
"type": "date",
"name": "Date",
"parent_id": 4
},
{
"id": 6,
"type": "money",
"name": "Amount",
"parent_id": 4
}
]
}
}
],
"deleted_or_closed": false,
"print_forms": [
{
"print_form_id": 2633,
"print_form_name": "templateA.docx"
},
{
"print_form_id": 2645,
"print_form_name": "templateB.xlsx"
}
],
"folder": [folder1]
}
]
}
curl
curl -X GET \ 'https://api.pyrus.com/v4/forms/' \ -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ -H 'Content-Type: application/json'
You can find a full list of field types in the Form fields format section.
GET /forms/{form-id}
This method returns a description of form with inputted id.
GET https://api.pyrus.com/v4/forms/36120
Response body
{
"id": 36120,
"name": "Payments",
"steps": {
"1": "Manager",
"2": "Accounting",
"4": "CEO"
},
"fields": [
{
"id": 1,
"type": "text",
"name": "Purpose",
"info": {
"required_step": 1,
"immutable_step": 1
}
},
{
"id": 2,
"type": "money",
"name": "Amount",
},
{
"id": 3,
"type": "catalog",
"name": "Payment type",
"info": {
"catalog_id": 277
}
},
{
"id": 4,
"type": "table",
"name": "Payment Schedule",
"info": {
"columns": [
{
"id": 5,
"type": "date",
"name": "Date",
"parent_id": 4
},
{
"id": 6,
"type": "money",
"name": "Amount",
"parent_id": 4
}
]
}
}
],
"deleted_or_closed": false,
"print_forms": [
{
"print_form_id": 2633,
"print_form_name": "templateA.docx"
},
{
"print_form_id": 2645,
"print_form_name": "templateB.xlsx"
}
],
"folder": [folder1]
}
curl
curl -X GET \ 'https://api.pyrus.com/v4/forms/36120' \ -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ -H 'Content-Type: application/json'
You can find a full list of field types in the Form fields format section.
GET /forms/{form-id}/register
This method returns the list of tasks that were created based on the specified form. The response only contains general information about the task, like the list of filled form fields and its workflow. You can use the GET /tasks/{task-id} method to get all task comments.
GET https://api.pyrus.com/v4/forms/1423/register
?fld2=gt10000,lt15000
&fld1=IT%20conference%20in%20Amsterdam
&fld3=277
&include_archived=y
Response body
{
"tasks": [{
"id": 11610,
"create_date": "2017-08-20T12:31:14Z",
"last_modified_date": "2017-08-23T10:20:11Z",
"current_step": 1,
"fields": [
{
"id": 1,
"type": "text",
"name": "Purpose",
"value": "IT conference in Amsterdam"
},
{
"id": 2,
"type": "money",
"name": "Amount",
"value": 10306.25
},
{
"id": 3,
"type": "catalog",
"name": "Payment type",
"value": {
"item_id": 845,
"headers": [
"Payment types"
],
"values": [
"IT Conference"
]
}
},
{
"id": 4,
"type": "table",
"name": "Payment Schedule",
"value": [
{
"row_id": 0,
"cells": [
{
"id": 5,
"type": "date",
"name": "Date",
"value": "2017-08-26",
"parent_id": 4,
"row_id": 0
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000,
"parent_id": 4,
"row_id": 0
}
]
},
{
"row_id": 1,
"cells": [
{
"id": 5,
"type": "date",
"name": "Date",
"value": "2017-08-27",
"parent_id": 4,
"row_id": 1
},
{
"id": 6,
"type": "date",
"name": "Amount",
"value": 306.25,
"parent_id": 4,
"row_id": 1
}
]
}
]
}
]
}]
}
curl
curl -X GET \ 'https://api.pyrus.com/v4/forms/327874/register?fld2=gt10000,lt15000&fld1=IT%20conference%20in%20Amsterdam&fld3=277&include_archived=y' \ -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ -H 'Content-Type: application/json'
If filtering parameters' size exceeds the maximum URL length, you can call this method via the HTTP POST request. Parameters are specified in the request body in JSON format.
{
"fld2": "gt10000,lt15000",
"fld1": "IT conference in Amsterdam",
"fld3": "eq277",
"include_archived": "y"
}
Parameters
| steps | Step number. You can specify multiple steps separated by a comma. |
| task_ids | The task numbers of the tasks the form register will be limited to. |
| include_archived | Specify "y" if you want to include archived tasks in the response. |
| field_ids | Field ids which values will be returned in the response. All fields are returned by default. You can specify multiple field ids separated by a comma. This parameter also affects the order of the returned fields in case of the csv format. If the parameter is not passed, all fields are returned. If the parameter is passed but does not contain ids, then form fields will be missing from the reply. |
fld{field_id} | Filter task by field:
lt and gt operators are applicable only to the following field types: date, money, number, due_date, creation_date. The "Is in list" operator is also applicable to the fields multiple_choice, catalog, person, author, form_link. Record identifier is used as a filter value for composite types. You can find additional information about field types in the Form fields format section. Filtering is not supported for the following field types: file, time, table, title, project, note. |
| format | Specify "csv", if you want to get the result in csv format. The default response format is json. |
| delimiter | Field separator in the csv file. By default — ",". |
| encoding | Response encoding. By default — "utf-8". |
| simple_format | Specify "y", if you want to get the csv file in the simplified format.All line breaks will be replaced with spaces. |
| modified_before | Tasks modified before specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ |
| modified_after | Tasks modified after specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ |
| created_before | Tasks created before specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ |
| created_after | Tasks created after specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ |
| closed_before | Tasks closed before specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ |
| closed_after | Tasks closed after specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ |
| item_count | Max. number of tasks in request.Value must be more than 0, and less than or equal to 20000. |
Form permissions
You can edit access rights to a form. To request the methods for this, email Pyrus tech support at support@pyrus.com. Read about form permissions in more detail here.
Access levels:
- "administrator" — form administrator;
- "manager" — form manager (without conditions);
- "member" — form participant;
- "none" — no access (only used when settings are changed to deny access to a user).
GET /forms/{form-id}/permissions
This method enables receiving a list of user permissions for the form.
GET https://api.pyrus.com/v4/forms/36120/permissions
Response body
{
"permissions": {
"1733": "manager",
"1731": "administrator"
}
}
curl
curl -X GET \ 'https://api.pyrus.com/v4/forms/327874/permissions' \ -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ -H 'Content-Type: application/json'
POST /forms/{form_id}/permissions
To change a user’s access rights, indicate the new rights for that user in the body of the reply. The format of the body of the reply is the same as for receiving the list of form permissions.
Limitations:
- the administrator’s rights cannot be edited, and new administrators cannot be added to the form;
- form managers cannot be added with conditions.
POST https://api.pyrus.com/v4/forms/36120/permissions
Request body
{
"permissions": {
"1733": "member"
}
}
Response body
{
"permissions": {
"1733": "member",
"1731": "administrator"
}
}
curl
curl -X POST \
https://api.pyrus.com/v4/forms/36120/permissions \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"permissions": {
"1733": "member"
}
}'