Bitrix24 v2

Provides integration with Bitrix24 using the REST 3.0 API to read and manage tasks, task results, notes, AI assistant scheduled tasks, custom field configurations, user consents and other portal records in your Workflows. Templates are built from the REST 3.0 API description acquired from your Bitrix24 portal.

Revision History

0.0.0.10 - Initial release.

Connection

Use this Connection to store your Bitrix24 portal address, OAuth application credentials and tokens, and the API description used to build templates.

Property Type Description
InstanceUrl String Required HTTPS address of your Bitrix24 portal, without a path, query or fragment. For example, https://example.bitrix24.com.
ClientId String Required client ID of your Bitrix24 OAuth application.
ClientSecret Masked Required client secret of your Bitrix24 OAuth application. It is sent only to the Bitrix24 OAuth token service.
AccessToken Masked OAuth access token used for API requests. Populated by authorization and renewed automatically.
RefreshToken Masked OAuth refresh token used to renew access. Populated by authorization and saved again whenever Bitrix24 issues a new token.
TimeoutSeconds Integer Maximum duration of each request to Bitrix24, in seconds. Defaults to 60 and must be greater than zero.

Setup Notes

  1. In your Bitrix24 portal, create or install an application that uses OAuth, and grant it the permissions required by the operations you plan to use.
  2. Register the callback address https://app.flowgear.net/r/auth as the application's return address. Bitrix24 reads the return address from the application settings.
  3. Create a Bitrix24 Connection in Flowgear and enter InstanceUrl, ClientId and ClientSecret.
  4. Authorize the Connection and sign in to your Bitrix24 portal when prompted.
  5. Run AcquireMetadata. This downloads the REST 3.0 API description from your portal and saves it on the Connection. Templates and Methods require this metadata.
  6. Test the Connection. The test downloads the API description using the saved tokens, without changing the saved metadata.
  7. Select a Method and its operation template, then map the fields needed by your Workflow.

The Node can run on Cloud and Run Anywhere Clusters.

Only one authorization attempt can be pending for a Connection, and starting a new attempt replaces the previous one. Each attempt can be completed only once. If authorization is declined or the token exchange fails, start authorization again.

Authorization confirms that the tokens issued by Bitrix24 belong to the portal in InstanceUrl. Tokens for a different portal are rejected.

Flowgear renews the access token automatically when Bitrix24 rejects it, and saves the new token pair on the Connection. Renewing tokens does not add permissions. If an operation fails because of missing permissions, update the application's permissions in Bitrix24 and authorize the Connection again.

Run AcquireMetadata again to refresh template names and descriptions, or after Bitrix24 changes the API available on your portal. If the acquired API description changes the type of a supported field or makes a new field required, the affected operation reports an error until compatible metadata is acquired.

Methods

Select an operation template for the Method you want to use. The template supplies OperationId, a GUID identifying that operation, and describes its Options or Items fields and its Response structure. Template names and descriptions come from the API description on your portal. When the portal does not provide them, the template is named after its REST method, such as tasks.task.list. An OperationId from a different Method is rejected.

Only operations that are present, not deprecated and compatible in your portal's API description are offered as templates. Some portals do not describe paging for note.collection.list, in which case that template is not available.

Method Supported operations
Query Tasks, task results and Gantt links. Note collections and documents. AI assistant scheduled tasks. Organisational structure nodes. Mailboxes, mail messages, senders and recipients. Event log entries, user history, user agreements, custom field configurations, smileys and smiley sets. Work time records.
Create Tasks and task results. Note collections and documents. Custom field configurations. User consents.
Update Tasks and task results. Note collections and documents. AI assistant scheduled tasks. Custom field configurations.
Delete Tasks and task results. Note collections and documents. AI assistant scheduled tasks. Custom field configurations.
Execute Pause or resume AI assistant scheduled tasks. Archive or move note collections and documents. Send a task chat message. Add a task result from a chat message.

Query

Reads the resource selected by the template. Paged list operations retrieve subsequent pages automatically as you consume Response. Get operations return a single record by ID.

Available operations:

  • Tasks: tasks.task.list, tasks.task.get, tasks.task.result.list and tasks.task.gantt.link.list.
  • Notes: note.collection.list, note.collection.get and note.document.get.
  • AI assistant scheduled tasks: aiassistant.scheduledtask.list and aiassistant.scheduledtask.get.
  • Organisational structure: humanresources.node.list, humanresources.node.search, humanresources.node.get and humanresources.node.children.
  • Mail: mail.mailbox.list, mail.mailbox.get, mail.mailbox.senders, mail.message.list, mail.message.get, mail.recipient.listcontacts and mail.recipient.listemployees.
  • Portal records: main.eventlog.list, main.eventlog.get, main.user.history.list, main.user.history.fields.list, main.user.agreement.list, main.user.agreement.get, main.userfieldconfig.list, main.userfieldconfig.get, main.smile.list and main.smileset.list.
  • Work time: timeman.record.list.
Parameter Type Description
Connection Connection Bitrix24 Connection used to authenticate the request.
OperationId String GUID supplied by the selected query template.
Options Object Values supported by the selected template, using Bitrix24's field names. For example, id for a get operation, or moduleId for custom field configuration operations. Unsupported fields are rejected.
Options.select String Comma-separated fields to return. Defaults to the fields shown by the template, such as id,title.
Options.filter String List operations only. A JSON array of conditions that must all match, such as [["id",">=",1]]. Leave it empty to return all records. tasks.task.result.list and tasks.task.gantt.link.list require a positive taskId equality condition, such as [["taskId","=",1]].
Options.order String List operations that support sorting. Comma-separated field:direction pairs in order of precedence, such as deadline:ASC,priority:DESC. Directions must be ASC or DESC. Leave it empty to use the default sorting.
Return Type Description
Response Array One row per returned record, without the Bitrix24 response envelope. Query rows do not include Flowgear metadata. A successful query with no matching records returns no rows.

Create

Creates one record for each item in Items using the selected template.

Available operations: tasks.task.add, tasks.task.result.add, note.collection.add, note.document.add, main.userfieldconfig.add and main.user.consent.add.

Parameter Type Description
Connection Connection Bitrix24 Connection used to authenticate the request.
OperationId String GUID supplied by the selected create template.
Items Array Required stream of records to create, using the fields shown by the template. For example, tasks.task.add items require title, creatorId and responsibleId, and note.document.add items require collectionId and title. main.userfieldconfig.add items supply moduleId and a fields object.
Return Type Description
Response Array One row per input item containing the created record, or an error object when Bitrix24 rejects the item. Each row includes Flowgear.IsSuccess, Flowgear.Message and the submitted item in Flowgear.Request.

Update

Updates one record for each item in Items. Each item identifies its target by id and supplies the changed values in a fields object.

Available operations: tasks.task.update, tasks.task.result.update, note.collection.update, note.document.update, aiassistant.scheduledtask.update and main.userfieldconfig.update.

Parameter Type Description
Connection Connection Bitrix24 Connection used to authenticate the request.
OperationId String GUID supplied by the selected update template.
Items Array Required stream of updates using the fields shown by the template.
Items.id Integer Required ID of the record to update.
Items.fields Object Required values to change, using the fields shown by the template.
Items.expectedVersion Integer Required for aiassistant.scheduledtask.update. The current version of the scheduled task.
Items.moduleId String Required for main.userfieldconfig.update. The module that owns the custom field.
Return Type Description
Response Array One row per input item containing the Bitrix24 result, or an error object when Bitrix24 rejects the item. Each row includes Flowgear.IsSuccess, Flowgear.Message and Flowgear.Request.

Delete

Deletes one record for each item in Items.

Available operations: tasks.task.delete, tasks.task.result.delete, note.collection.delete, note.document.delete, aiassistant.scheduledtask.delete and main.userfieldconfig.delete.

Parameter Type Description
Connection Connection Bitrix24 Connection used to authenticate the request.
OperationId String GUID supplied by the selected delete template.
Items Array Required stream of records to delete.
Items.id Integer Required ID of the record to delete.
Items.expectedVersion Integer Required for aiassistant.scheduledtask.delete. The current version of the scheduled task.
Items.moduleId String Required for main.userfieldconfig.delete. The module that owns the custom field.
Return Type Description
Response Array One row per input item containing the Bitrix24 result, or an error object when Bitrix24 rejects the item. Each row includes Flowgear.IsSuccess, Flowgear.Message and Flowgear.Request.

Execute

Runs the selected Bitrix24 action once for each item in Items.

Available operations:

  • aiassistant.scheduledtask.pause and aiassistant.scheduledtask.resume - Pause or resume a scheduled task. Items require id and expectedVersion.
  • note.collection.archive and note.document.archive - Archive a note collection or document. Items require id.
  • note.collection.move and note.document.move - Move a note collection or document. Items require id and can include a new position. Documents can also include collectionId and parentId.
  • tasks.task.chat.message.send - Send a message to a task's chat. Items require taskId and text.
  • tasks.task.result.addfromchatmessage - Add a task result from an existing chat message. Items require messageId and can include text.
Parameter Type Description
Connection Connection Bitrix24 Connection used to authenticate the request.
OperationId String GUID supplied by the selected execute template.
Items Array Required stream of action inputs using the fields shown by the template.
Return Type Description
Response Array One row per input item containing the Bitrix24 result, or an error object when Bitrix24 rejects the item. Each row includes Flowgear.IsSuccess, Flowgear.Message and Flowgear.Request.

Usage Notes

  • Use the exact field names and value types shown by the selected template. Unsupported fields and values of the wrong type are rejected before the request is sent. Text values are not trimmed.
  • Paging is managed by the Node, 50 records per page. Do not supply paging values in Options.
  • Options.filter supports the =, !=, >, >=, <, <=, in and between operators. Each condition is [field,value] or [field,operator,value], and all conditions must match. in requires an array value, and between requires an array of two values. OR conditions and grouped conditions are not supported.
  • Comma-separated values such as Options.select and Options.order follow CSV rules. Quote values that contain commas, quotes or line breaks, and double any embedded quotes. Spaces are preserved.
  • Create, Update, Delete and Execute require Items to be connected. An empty Items stream sends no requests and returns no rows. Each item is sent as a separate request, so multiple items are not processed as a single transaction.
  • Inspect Flowgear.IsSuccess on each mutation result. When Bitrix24 rejects an individual item, the Node returns a failed row with the Bitrix24 error code, message and any field validation details, then continues with later items. Authentication, permission, connection and server failures stop the operation.
  • tasks.task.add and tasks.task.update reject an empty title before the request is sent. Omit title from an update to leave it unchanged.
  • For tasks.task.update, Bitrix24 reports a missing task and a task you cannot access in the same way. The Node returns a failed row stating that the task was not found or is not accessible, and continues with later items.
  • When Bitrix24 limits the request rate, the Node waits and retries a limited number of times. If the required wait is longer than about ten seconds, the operation fails so that you can retry after the Bitrix24 limit resets.

See also