EventBridge

🚨 The EventBridge integration is in Early Access and we're working with a small number of design partners to productize it. We are aiming to be included in the AWS EventBridge SaaS partner directory in the near future. If you want in as a design partner, please get in touch with your customer success representative!

Overview

The EventBridge integration allows customers to receive notifications and requests from Control Room directly to AWS EventBridge event bus on their account.

Currently, the following types of events are supported:

• Self-hosted On-Demand Worker requests. This allows implementing the on-demand worker API without exposing a REST endpoint on the internet.

Fundamentals

The integration is configured at Control Room organization level. Integration configured for an organization can be utilized in any workspace belonging to the organization. Initially, the integration is configured by the Robocorp team, without a self-service interface.

Configuration

Enable the integration on AWS account as follows:

• Determine identifier of the Robocorp Control Room instance your organization is deployed on. If you don't know, get in touch with your customer success representative.
• Determine identifier of the Control Room organization for which the integration will be configured. The ID can be viewed in Control Room Organization Configuration on the Settings tab.
• Create an AWS EventBridge Event Bus on your AWS account.
• Add an Event Bus Policy that grants Control Room access to put events to your Event Bus. Note that the policy is specific to the Control Room instance and your organization identifier.
  • eu1 (Ireland): arn:aws:events:eu-west-1:467232950774:rule/eu1-customer-integration/org-[ORGANIZATION-ID]
  • eu2 (Frankfurt): arn:aws:events:eu-central-1:257651247968:rule/eu2-customer-integration/org-[ORGANIZATION-ID]
  • us1 (North Virginia): arn:aws:events:us-east-1:312661337933:rule/us1-customer-integration/org-[ORGANIZATION-ID]
• Send the following information to your Robocorp Customer Success representative:
  • ARN of the event bus receiving the events
  • ID of the Control Room organization
• We'll be in touch with further instructions once the configuration is complete

Example of a commplete Event Bus Policy:

Event Message Structure

The events originating from Robocorp Control Room are designed according to the AWS EventBridge Event Structure reference. This section describes the general principles and guidelines for implementing the event consumers.

• source is specific to the integration configuration and may contain e.g. unique identifiers. Content of the source field is expected to change once the integration is published as AWS EventBridge SaaS partner integration, and we encourage not building any rules that depend on the source field at this point in time.
• resources array identifies the Control Room Organization and Workspace involved in the event. Currently, the resources array always contain a single element of format robocorp-control-room/organization-[organization_id]/workspace-[workspace_id]. For convenience, the organization and workspace identifiers are always included in the detail object as well; therefore it is not mandatory for the event consumers to parse content of the resources array.
• detail-type specifies the type of the event in question. The value of the detail-type field alone always identifies the semantics and the structure of the event. We specify the events per detail-type, and we recommend basing any parsing and functional routing logic on the detail-type field.

Backwards and forwards compatibility

The detail-type field implicitly includes version of the message format. Once a message has been published, breaking changes to the format will not be introduced. However, additional fields may be introduced to existing messages and therefore the client implementaton must tolerate additional fields.

Events

This section describes the individual event types supported by this integration.

On-Demand Worker Request

Control Room uses this event to request a compute resource to be started for execution of a step run.

The detail-type is set to value On-Demand Worker Request.

The detail object contains the following fields:

• metadata object contains non-sensitive metadata of the request and has the following properties:
  • organization_id identifies the Control Room organization
  • workspace_id identifies the Control Room workspace
  • process_id identifies the Control Room process
  • step_id identifies the step inside the process
  • on_demand_worker_id identifies the On-Demand worker configuration in Control Room
  • step_run_id identifies the step run the worker is created for
  • process_run_id identifies the process run which the step run belongs to
  • process_run_number number of the process run in question
  • worker_id is an unique identifier for the worker to be started
  • max_execution_seconds specifies the maximum duration of the task execution. This value is dictated by the timeout specified for the step in question. The client can utilize this value with a safeguard timer that ensures all tasks get eventually terminated.
• encryption_scheme defines mechanism used to encrypt the subsequent payload. Encryption scheme can have the following values:
  • AWS-ENCRYPTION-SDK: AWS Encryption SDK with the following parameters:
    • Key name: on-demand-worker-secret
    • Key namespace: robocorp
    • Wrapping suite: AES256_GCM_IV12_TAG16_NO_PADDING
    • The ECS on-demand worker example includes a NodeJS (TypeScript) implementation of the decryption.
• encrypted_payload contains base64-encoded encrypted data block of the sensitive payload. Once decrypted, the payload contains the following properties:
  • worker_link_token is one-time-use token used to link the worker for allocation of the workload. The receiving implementation must pass the token to Robocorp Worker running in the compute to be launched.
• 🚨 [DEVELOPMENT MODE ONLY] payload (if present) contains a plaintext version of the payload. This allows testing and building the infrastructure without having to implement the decryption.

Full payload example: