This repository has been archived by the owner on Jun 27, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 120
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
d2cb154
commit f0da265
Showing
16 changed files
with
754 additions
and
89 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| # App Configuration | ||
|
|
||
| It consists primarily of providing settings that the Apps Engine will then present on the administration interface for the workspace administrator to configure and launch the application.  | ||
|
|
||
| Everything under the **Settings** menu of the app within a marketplace belongs under the **App Configuration** section. This tab contains various fields and instructions that can be filled out. What you see on this screen must be configured for the application, and that's what this section is about.  | ||
|
|
||
| Here are some key terms you need familiarize yourself with:  | ||
|
|
||
| * ID - for identifying the settings | ||
| * Type - the type of the value that will be saved | ||
| * Required - whether or not configuring the application is required | ||
| * Package value - the default value before the administrator can configure anything | ||
| * I18n label - the translated name or description of an application  | ||
|
|
||
| \ | ||
| There is a distinct file containing the configuration settings, in which everything is defined as a basic object. In this file, each setting is defined separately. In the `extendConfiguration` method, you simply read the file, and for each setting, it calls the `provideSetting` method, so that each setting that is defined is read, called, and displayed in the user interface.  | ||
|
|
||
| This is equivalent to executing the command:  | ||
|
|
||
| ``` | ||
| configuration.settings.provideSetting ({ | ||
| Define all the parameters of your setting | ||
| } ) | ||
| ``` | ||
|
|
||
| Since your app may have multiple settings, it is preferable to organize them all in a separate file and reference them as required in the app's main file.  | ||
|
|
||
| Here are the various categories of configurations that Rocket.Chat supports. Each of these will appear differently within the **Settings** tab of the app in the marketplace.  | ||
|
|
||
| * Boolean | ||
| * Code | ||
| * Color | ||
| * Font | ||
| * Number | ||
| * Select | ||
| * String | ||
| * Multi-select | ||
|
|
||
| The `onSettingUpdated` method will be invoked each time the administrator modifies the application's configuration via the **Settings** panel. The method will use the new value to make adjustments as necessary. You can use this, for instance, to inform an external service that the parameters have changed and the values have been updated. In the case of `onPreSettingUpdate`, you will receive both the old and updated settings values. The App Lifecycle document explains the various methods and their corresponding statuses in greater detail.  | ||
|
|
||
| It is common in integrations to want to always transmit certain security protocols for API requests. In the case of the Rocket.Chat REST API, these headers are X-Auth-Token and X-User-Id. Therefore, it would be desirable if these headers were always set when making API queries. In such situations, it is customary to generate a personal access token in Rocket.Chat. Read the [Access Tokens Endpoint documentation](https://developer.rocket.chat/reference/api/rest-api/endpoints/other-important-endpoints/access-tokens-endpoints) for more information. In such cases, it makes sense to add configuration parameters to the application. These are configured in the `extendConfiguration` method of the application's primary class.  | ||
|
|
||
| The **client ID** and **client secret** are routinely generated by one of the mechanisms for the app settings. Client ID and client secret would almost always be required by apps. Therefore, Rocket.Chat has supplied a code template that developers can utilize without having to code it themselves. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| # App Data Persistence | ||
|
|
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| # App Internationalization | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| # Extending App Capabilities | ||
|
|
||
| `IConfigurationExtend` is the accessor that offers methods for declaring your application's configuration. It is provided during application initialization. This is how the app can be expanded or new features added. Register some of your app's capabilities using this method. | ||
|
|
||
| <table><thead><tr><th width="221.5">Property</th><th>Purpose</th></tr></thead><tbody><tr><td>api</td><td>Accessor for API endpoint declarations</td></tr><tr><td>http</td><td>Accessor for configuring how your application handles HTTP requests and responses</td></tr><tr><td>scheduler</td><td>Accessor for designating tasks that can be scheduled</td></tr><tr><td>settings</td><td>Accessor for declaring the configurations your app offers</td></tr><tr><td>slashCommands</td><td>Accessor for declaring the commands that your app provides</td></tr><tr><td>ui</td><td>Accessor for registering the various host UI elements</td></tr><tr><td>videoConfProviders</td><td>Accessor for declaring the video conferencing providers your app offers</td></tr></tbody></table> | ||
|
|
155 changes: 155 additions & 0 deletions
155
apps-engine/extending-app-capabilities/http-requests.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,155 @@ | ||
| # HTTP Requests | ||
|
|
||
| This document will explain how to connect your Rocket.Chat application to the outside world. The HTTP property permits users to invoke an external web service. In this article, we will construct a slash command that executes a GET HTTP request based on the supplied parameters. You will require the following:  | ||
|
|
||
| * A Rocket.Chat server to deploy the app to | ||
| * Our[ Tester App](https://github.com/RocketChat/Apps.RocketChat.Tester) or a newly created app (of your choice) | ||
|
|
||
| ### Step 1: Register the slash command | ||
|
|
||
| The slash command must be registered in the app's main class, at the root of the project. | ||
|
|
||
| ```typescript | ||
| import { IAppAccessors, IConfigurationExtend, ILogger } from '@rocket.chat/apps-engine/definition/accessors'; | ||
| import { App } from '@rocket.chat/apps-engine/definition/App'; | ||
| import { IAppInfo } from '@rocket.chat/apps-engine/definition/metadata'; | ||
| import { HTTPRequestCommand } from './slashcommands/HTTPRequestCommand'; // [1] | ||
|
|
||
| export class RocketChatTester extends App { | ||
| constructor(info: IAppInfo, logger: ILogger, accessors: IAppAccessors) { | ||
| super(info, logger, accessors); | ||
| } | ||
|
|
||
| public async extendConfiguration(configuration: IConfigurationExtend) { | ||
| configuration.slashCommands.provideSlashCommand(new HTTPRequestCommand()); // [2] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Here, we \[1] import our new slash command class and then \[2] register it in the configuration of the application. | ||
|
|
||
| ### Step 2: Create the slash command | ||
|
|
||
| Our command will be referred to as get, so to invoke it from the conversation, simply enter `/get <url>`. | ||
|
|
||
| Create a `slashcommand` directory at the root of the project and add the `HTTPRequestCommand.ts` file to it. Then paste the code shown below: | ||
|
|
||
| ```typescript | ||
| import { | ||
| IHttp, | ||
| IModify, | ||
| IRead, | ||
| } from '@rocket.chat/apps-engine/definition/accessors'; | ||
| import { | ||
| ISlashCommand, | ||
| SlashCommandContext, | ||
| } from '@rocket.chat/apps-engine/definition/slashcommands'; | ||
|
|
||
| export class HTTPRequestCommand implements ISlashCommand { | ||
| public command = 'get'; // [1] | ||
| public i18nParamsExample = ''; | ||
| public i18nDescription = ''; | ||
| public providesPreview = false; | ||
|
|
||
| public async executor(context: SlashCommandContext, read: IRead, modify: IModify, http: IHttp): Promise<void> { | ||
| const [url] = context.getArguments(); // [2] | ||
|
|
||
| if (!url) { // [3] | ||
| throw new Error('Error!'); | ||
| } | ||
|
|
||
| await http.get(url); // [4] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| This code indicates:  | ||
|
|
||
| * \[1] The command will be called get. | ||
| * When executed, \[2] it uses the argument that the user passed after the command as the URL. | ||
| * \[3] The argument is required | ||
| * \[4] Perform the get request using the provided argument. | ||
|
|
||
| You can optionally store the `GET` request in a console constant. When the command is executed, it is logged. | ||
|
|
||
| ```typescript | ||
| const response = await http.get(url); | ||
| console.log("result: " + response.data); | ||
| ``` | ||
|
|
||
| ### Step 3: Deploy to the server | ||
|
|
||
| To deploy the app, run:  | ||
|
|
||
| ``` | ||
| rc-apps deploy --url <server_url> -u <user> -p <pwd> | ||
| ``` | ||
|
|
||
| The `<server_url>` parameter is the URL of your Rocket.Chat server. Replace the placeholders with the URL, username, and password for the server. After executing this command, your application will begin to be deployed to the server. | ||
|
|
||
| #### Packaging your app | ||
|
|
||
| Alternatively, you can execute the `rc-apps package`, which will provide you with a compressed zip file of your app that you can upload as a private app to your Rocket.Chat server.  | ||
|
|
||
| ### Step 4: Testing the app by calling the slash command | ||
|
|
||
| After deploying the application, you can input `/get some_url>` in any channel and the app will send a `GET` request to the specified URL. In this example, we will utilize [JSONPlaceholder](https://jsonplaceholder.typicode.com) to obtain dummy data for testing our application: | ||
|
|
||
| * Enter `/get https://jsonplaceholder.typicode.com/todos/1` in a chat | ||
| * Your Rocket.Chat instance will print out to the console the following:\ | ||
| `result: {"userId":1,"id":1,"title":"delectus aut autem","completed":false}` | ||
|
|
||
| **Note:** If you do not see the result, enable info logs in your instance by selecting "**1 - Errors and Information**" at **Administration** > **Logs** > **Log** **Level**. | ||
|
|
||
| ### Print the request in the chat  | ||
|
|
||
| Now, instead of logging console output to the instance's log, let's output it to the conversation. | ||
|
|
||
| Add the following private method to `HTTPRequestCommand.ts`. | ||
|
|
||
| ```typescript | ||
| private async sendMessage(context: SlashCommandContext, modify: IModify, message: string): Promise<void> { | ||
| const messageStructure = modify.getCreator().startMessage(); | ||
| const sender = context.getSender(); // [1] | ||
| const room = context.getRoom(); // [2] | ||
|
|
||
| messageStructure | ||
| .setSender(sender) | ||
| .setRoom(room) | ||
| .setText(message); // [3] | ||
|
|
||
| await modify.getCreator().finish(messageStructure); // [4] | ||
| } | ||
| ``` | ||
|
|
||
| \ | ||
| This function \[1] gets the user who invoked the command (in this case, you), \[2] selects the room where the command was executed, \[3] sets the received string as the message, and \[4] sends the message to the room.\ | ||
| \ | ||
| **Note:** To learn more about messaging, please visit the [IMessageBuilder](https://rocketchat.github.io/Rocket.Chat.Apps-engine/interfaces/accessors\_imessagebuilder.imessagebuilder.html) documentation.\ | ||
| \ | ||
| Then, append the following code to the end of the executor method: | ||
|
|
||
| ```typescript | ||
| const response = await http.get(url); // [1] | ||
| const message = JSON.stringify(response.data, null, 2); // [2] | ||
| await this.sendMessage(context, modify, message); // [3] | ||
| ``` | ||
|
|
||
| Instead of simply sending the request and not capturing the response, we \[1] store the response in a constant, \[2] format its content as a string, and \[3] transmit it using our new `sendMessage` method. | ||
|
|
||
| Save the file and redeploy the app by running: | ||
|
|
||
| ``` | ||
| rc-apps deploy --url <server_url> -u <user> -p <pwd> --update | ||
| ``` | ||
|
|
||
| Now, when you execute the slash command `/get https://jsonplaceholder.typicode.com/todos/1`, you will receive the following response in the chat: | ||
|
|
||
| ```typescript | ||
| { | ||
| "userId": 1, | ||
| "id": 1, | ||
| "title": "delectus aut autem", | ||
| "completed": false | ||
| } | ||
| ``` |
Oops, something went wrong.