To integrate AWS AppSync in your OutSystems app, simply follow these steps:

Preparation of AWS AppSync

Please configure the AppSync GraphQL API if you have not done so yet. If you are not familiar with AppSync, you can find more information in the AWS documentation. Open the AWS AppSync console and look up the following connection parameters in the "Settings" area, as you will need them to configure the connector.

• GraphQL endpoint (https URL)
• Real-time endpoint (wss URL)
• API key

For now, the connector only supports API key for authentication. You should consider further securing the endpoint using WAF.

Install the AWS AppSync Connector

Install this AWS AppSync Connector from the Forge to your OutSystems environment.

Client-Side

For the client-side implementation, you need to add a dependency to the AWSAppSyncClient widget.

• To send GraphQL requests (query or mutate data), you also need to add the client action AWSAppSyncClient_SendGraphQLRequest.
• To receive real-time messages, you need to add the client actions AWSAppSyncClient_Connect, AWSAppSyncClient_Disconnect, AWSAppSyncClient_StartSubscription and AWSAppSyncClient_StopSubscription.
• Client action AWSAppSyncClient_GetDetail optionally allows you to get the current status of the real-time connection and list active subscriptions.
• AWSAppSyncClient_SendRealtimeMessage allows you to send custom messages via the web socket connection.

Place the AWSAppSyncClient block onto the screen where you want to use real-time communication an configure the connection via the provided input parameters:

• SubscriberId: Id of the subscriber (e.g. widget id)
• RealtimeHost: AWS RealTime endpoint host without protocol and path
• GraphQLHost: AWS GraphQL endpoint host without protocol and path
• ApiKey: AWS AppSync API key
• IsAutoReconnect: True to enable automatic reconnect (optional, default is True)

To react on status changes and incoming messages, add handler actions for the following events the block exposes:

• OnWebSocketUnsupported: Triggered during initialization when the browser is not supporting websockets
• OnConnection: Triggered when the connection state of the AWSAppSyncClient changed
• OnSubscription: Triggered when the state of a subscription changed
• OnMessage: Triggered when a message is received
• OnError: Triggered when an error has occurred

To interact with the AWSAppSyncClient there are several client actions. To identify the block you want to address, you need to pass the SubscriberId as input parameter:

• AWSAppSyncClient_Connect: Establishes the websocket connection and initializes the handshake.
• AWSAppSyncClient_Disconnect: Stops all active subscriptions and then closes the websocket connection.
• AWSAppSyncClient_GetDetail: Returns details of the AWSAppSyncClient.
• AWSAppSyncClient_StartSubscription: Starts a subscription.
• AWSAppSyncClient_StopSubscription: Stops a subscription.
• AWSAppSyncClient_SendRealtimeMessage: Sends a message to the AWS AppSync realtime endpoint via the websocket connection.
• AWSAppSyncClient_SendGraphQLRequest: Sends a request to the AWS AppSync GraphQL endpoint via https.

Server-Side

For the server-side implementation, you only need to add a dependency to the server action AWSAppSync_SendGraphQLRequest:

• AWSAppSync_SendGraphQLRequest: Sends a request to the AWS AppSync GraphQL endpoint via https.