Working with Services

Use the following blocks to work with various services:

• Get calendars
• Get calendar events
• Send email
• Send request
• Execute code

Get Calendars

Use this block to retrieve the list of employee calendars.

In the block parameters, enter the user’s email address manually or via mapping in the Domain/username field.

After execution, the block returns a list of the user’s calendars, which can be used in the Get Calendar Events block.

The block returns the following fields:

Get Calendar Events

This block retrieves a list of events from a calendar obtained with the Get Calendars block.

Parameters of the block:

• Calendar identifier (mandatory field, filled in manually or with the help of mapping)
• Email address
• Event collection start date

If the Event collection start date field is:

• Filled with a timestamp in milliseconds, only events starting from that date are displayed. The date value is based on the event start time. In this case, non-recurring events appear as usual, while recurring events are broken down into individual meetings. Canceled events are not displayed
• Filled with a SyncState value, the output includes all recurring, non-recurring, and canceled events created or updated since the last script run. SyncState is unique to each event and refers to the last modification date. You do not need to manually merge new and old data — using SyncState ensures automatic event synchronization

Detailed instructions for initial synchronization and SyncState usage are provided below.

The block outputs event data from the specified calendar. Based on the retrieved data, you can build tables and workflows.

The block returns the following fields:

Initial Synchronization

Initial synchronization occurs the first time the Get Calendar Events block runs, when no SyncState is yet available:

1. In the Start date for event collection field, specify the start date in Unix time (milliseconds). Example: 1609459200000 (January 1, 2021). The system will retrieve all events from this date until the request execution moment. This step initializes SyncState, which is used for further synchronization. Choosing a short range (e.g., one day) minimizes load during initial sync.
2. After a successful request, the system returns a SyncState value — a unique synchronization state ID that can be stored in a separate table. Save the calendar ID (unique_id), event ID (id_meeting), and the corresponding SyncState.

Using SyncState for Subsequent Runs

SyncState is a timestamp automatically generated by Microsoft Exchange when querying a calendar. It ensures only new or updated events since the last sync are retrieved.

For subsequent script runs, insert SyncState into the Start date for event collection field.

• If SyncState is found, only new or updated events since the recorded time are returned
• If no SyncState is found, the block execution for that calendar stops, and the script proceeds to the next one. If no SyncState values are stored for any calendars, the script stops entirely

SyncState updates only after successful processing of all calendars.

If an error occurs during synchronization, the new SyncState is not generated, and the previous one is reused, ensuring no data is missed.

If error ignore mode is enabled, the block continues execution even if some calendars fail. In this case:

• Successfully processed calendars update their events and SyncState
• Calendars with errors retain the previous SyncState, and error details are logged

During the next run, calendars with errors will be retried.

Benefits of using SyncState:

• Processes only new or updated events, reducing system load
• Excludes unchanged events, avoiding duplicates
• Ensures continuous and up-to-date event collection without manual tracking

Event Processing

When using a timestamp in milliseconds:

• Non-recurring events are returned as usual, starting from the specified date
• Recurring events are broken into separate instances for detailed analysis
• Canceled events are excluded from the output

When using SyncState:

• If a meeting has not changed (i.e., its last_modified_time remains the same) since the previous export, it will not be included in the response when the SyncState parameter is used. This prevents reprocessing of unchanged events. The SyncState value itself remains unchanged
• If changes occurred in a recurring event between exports (e.g., meeting details were updated), the response will include the updated data for that event
• If multiple changes occurred to a meeting between exports, only the event with the latest last_modified_time will be returned in the output. Intermediate changes do not result in multiple exports—only the final state of the event is considered

Error Ignore Mode

The Get calendar events block can operate in error-ignoring mode, which allows the script to continue executing even if individual calendars trigger errors. If an error is not included in the list of retryable or ignorable errors, the calendar where the error occurred will be skipped. This information is recorded in the automation agent logs and can be analyzed later. All other calendars continue to be processed normally.

Enable/disable error ignore mode in com.operavix.subsystem.automation.json via the parameter exchange_ignore_exceptions:

• true — error ignore mode enabled
• false — error ignore mode disabled (default)

If an error occurs repeatedly, it is recommended to run the script in error-ignoring mode. The automation agent logs will record the errors along with the identifiers of the calendars where they occurred. This information can be used for detailed analysis. After resolving the root cause of the error, it is recommended to disable error-ignoring mode and restart the central server to return to standard operation mode.

Example log entry:

2025-04-07 12:48:50.885+0300 [00000002] [X] DEBUG c.i.s.a.b.e.e.g.AppointmentIteratorItem:64 - Exchange ignoreExceptions mode enabled. All records skipped for id:AAMkAGQ4ZGFlMTU1LWYxYzEtNGQ4Ni1iMDFjLTNmZjAxMTk2YzI4ZgAuAAAAAADfJqMIbKSgS5+alO5Y+noFAQCU/9Lman9lR5EXIo0RRpHGAAAAAAENAAA=
com.operavix.platform.exception.PlatformException: The folder to be synchronized could not be found

Explanation:

• id — skipped calendar ID
• PlatformException — error that caused the calendar to be skipped

Using the Microsoft Exchange Package

To retrieve a list of calendars and store them in a database, build the following script:

1. Use the Scheduler block as the trigger and configure the schedule for fetching the list of calendars and their events.
2. Configure the Select rows by SQL query block for the target database to retrieve the list of user email addresses (logins) whose calendars need to be fetched.
3. Set up the Get calendars block. In the User's email address field, use mapping to insert the column containing the user email addresses obtained from the previous Select rows by SQL query block.
4. To retrieve calendar events, configure the Get calendar events block. In the Calendar ID field, use mapping to insert the unique_id tag. If you need to fetch events for a specific calendar only, enter the ID manually: go to the output data of the previous block and copy the unique_id value of the desired calendar. For the initial event collection, fill in the Event collection start date field with a timestamp in milliseconds.
5. To store the updated SyncState values (obtained in the previous step) in the database, add an Insert rows block from the appropriate package. In the Table field, select the target table. If you need to add a new column, click Add column.
6. Test the entire script by clicking Run test in the top right corner. If the test succeeds, publish and activate the script.

Send email

Use this block to Send emails to a specified email address.

Parameters:

• Connection — choose existing or add new
• Recipient address
• Letter subject
• Message — format Text or HTML
• Attachment
• Copy
• Hidden copy

All block parameters except connection can be mapped.

Emails can be sent either using the SMTP connection configured or via the System mail package by selecting the Send email block.

For standalone setups, configure the outgoing mail server for the System mail package.

Block specifics:

• The block can use values only from one source block. If values from multiple sources are mapped, an error occurs
• Another block must precede it. The number of emails sent depends on the number of records returned by the previous block. For example, if 5 records are returned, 5 emails will be sent
• Multiple recipients can be specified in the Recipient address field, separated by commas

Example:

1. Add the Send email block to the script and enter the recipient's address. For multiple recipients, list them separated by commas. Fill in other fields and click Test.
2. After the test, the email is sent to the specified addresses.

Send request

Use this block to send an HTTP request to a specified address.

Parameters:

• Connection — choose existing or add new
• URL
• Method — GET, POST
• Headers — key-value pairs
• Request body — for POST
• Batch processing — for POST, enables faster sending of multiple data packets

The method is selected from the dropdown list. All other parameters can be entered manually or mapped.

If authentication is required:

1. Go to the Connection tab.
2. Click + New connection and fill in:
   • Name
   • Username
   • Password
3. Click Create.

Connections can also be configured in the Control Panel.

Example:

1. Enter the URL, remove headers, and click Run test to test the block.
2. When the test is completed, you get the output data in the Test tab.

Running a Script via GraphQL Request

1. Retrieve the script GUID and workspace ID with this query in GraphiQL:
   query{
     automation{
       script{
         script_general(id: <script_id>){
           id
           guid
           workspace{
             id
           }
         }
       }
     }
   }
   

   You can also obtain the workspace ID from the workspace system table if you have the System Tables privilege enabled.
2. In the Send request block, enter your GraphQL server URL with the API key: https://{server_address}/graphql?api_key=key.
3. Select the POST method.
4. In the Body field, enter:
   {"query":"mutation{
     automation{
       script{
         execute_by_guid(guid:\"<obtained_script_GUID>\", workspace_id:<obtained_workspace_id>){
           guid
         }
       }
     }
   }"}
   

   
5. Click Run test.
6. When the test is complete, you get the output data in the Test tab.

Execute Code

This block processes data using JavaScript.

Use this block to:

• Perform multiple/related HTTP requests
• Upload/download files using HTTP requests
• Perform mathematical operations on variables
• Parse JSON strings and filter values

To execute an action, enter the JS code in the JavaScript field in the block parameters. You can use mapping to insert variables into the code.

The block can contain z-method for hashing and error handling. The following methods can be used for execution in the JS environment:

• z.base64Encode() — performs base64 encoding of the input string. Example: const auth = z.base64Encode(login + ':' + password);
• z.base64Decode() — performs base64 decoding of the input string. Example: const originalText = z.base64Decode(encodedText);
• z.request() — performs an HTTP request. Expects an object with the request configuration as input. Parameters:
  • url — address to which the request will be sent
  • method — defaults to GET. Possible values: GET, POST, DELETE, PUT
  • headers — list of HTTP request headers
  • jsonBody/multipartBody — request body. Required for POST and PUT methods
  • timeout — individual server response timeout in milliseconds

Running a Script with JS Code

1. Enter the code in the JavaScript field:
   const apiKey = 'key';
   const scriptGuid = 'script_GUID';
   const workspaceId = 1;
   
   var resp1 = z.request({
       url: 'https://server_address/graphql?api_key=' + apiKey,
       method: 'POST',
       jsonBody: '{"query":"mutation{automation{script{execute_by_guid(guid:\\"' +     scriptGuid + '\\", workspace_id:' + workspaceId + '){guid}}}}"}'
   });
   
   const app = {
       output: () => ({
               resp_1_body: JSON.stringify(resp1.response),
               resp_1_header: JSON.stringify(resp1.headers),
               resp_1_status: resp1.status,
               ["var-with-hard-name-1"]: resp1.headers.date,
               ["var-with-hard-name-2"]: resp1.headers["cache-control"],
               content_type: resp1.headers["content-type"],
               content_length: resp1.headers["content-length"]
           }
       )
   }
   

2. Click Run test.
3. When the test is complete, you can see the output data in the Test tab.

Getting a File from Jira

1. Enter the code in the JavaScript field:

const login = 'login';
const password = 'password';
const auth = z.base64Encode(login + ':' + password);

var resp1 = z.request({
    url: 'https://jira.office.operavix.com/secure/attachment/76158/Screenshot_1.jpg',
    method: 'GET',
    headers: {
        Authorization: 'Basic ' + auth
    }
});

    const app = {
        output: () => ({
                resp_1_body: JSON.stringify(resp1.response),
                resp_1_header: JSON.stringify(resp1.headers),
                resp_1_status: resp1.status,
                file_content: resp1.response,
                ["var-with-hard-name-1"]: resp1.headers.date,
                ["var-with-hard-name-2"]: resp1.headers["cache-control"],
                content_type: resp1.headers["content-type"],
                content_length: resp1.headers["content-length"]
            }
        )
    }

1. Click Run test.
2. When the test is complete, you can see the output data in the Test tab.