Skip to content

Commit

Permalink
Merge pull request #6 from sachinira/teams
Browse files Browse the repository at this point in the history 
Update documentations to new staructure
  • Loading branch information
@abeykoon
abeykoon authored Aug 10, 2021
2 parents 96ec9e1 + 8c3d7f0 commit c38da3b
Show file tree
Hide file tree
Showing 7 changed files with 134 additions and 244 deletions.
54 changes: 23 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,53 +6,45 @@ Ballerina Microsoft Teams Connector

[Microsoft Teams](https://www.microsoft.com/en-ww/microsoft-teams/group-chat-software) is a chat-based collaboration
platform complete with document sharing, online meetings, and many more extremely useful features for business
communications.

Ballerina connector for Microsoft Teams has developed on top of Microsoft Graph is a REST web API that empowers you to
access Microsoft Cloud service resources. This version of the connector only supports the access to the resources and
information of a specific account (currently logged-in user).

For more information, go to the module(s).
- [ballerinax/microsoft.teams](https://docs.central.ballerina.io/ballerinax/microsoft.teams/0.1.0)

## Building from the Source
### Setting Up the Prerequisites
1. Download and install Java SE Development Kit (JDK) version 11 (from one of the following locations).

* [Oracle](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html)

* [OpenJDK](https://adoptopenjdk.net/)
communications. It provides the capability to connect to the MS Teams platform API in Microsoft Graph via Ballerina.
It allows you to perform basic functionalities provided in MS Teams such as sending messages, viewing messages,
creating teams, channels, and chats, deleting and updating resources, etc., programmatically. This version of the
connector only supports the access to the resources and information of a specific account (currently logged-in user).

> **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed
JDK.
For more information, see module(s).
- [microsoft.teams](teams/Module.md)

2. Download and install [Ballerina](https://ballerina.io/)
## Building from the source
### Setting up the prerequisites
1. Download and install Java SE Development Kit (JDK) version 11. You can install either [OpenJDK](https://adoptopenjdk.net/) or [Oracle JDK](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html).
> **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK.
2. Download and install [Ballerina Swan Lake Beta2](https://ballerina.io/)

### Building the source

### Building the Source

Execute the commands below to build from the source.
Execute the following commands to build from the source:

1. To build the package:
- To build the package:
```
bal build -c ./teams
```
2. To run the without tests:
- To build the package without tests:
```
bal build -c --skip-tests ./teams
```
## Contributing to Ballerina
## Contributing to ballerina

As an open source project, Ballerina welcomes contributions from the community.

For more information, go to the [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md).
For more information, see [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md).

## Code of Conduct
## Code of conduct

All contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct).

## Useful Links
* Discuss code changes of the Ballerina project in [ballerina-dev@googlegroups.com](mailto:ballerina-dev@googlegroups.com).
## Useful links

* Discuss code changes of the Ballerina project via [ballerina-dev@googlegroups.com](mailto:ballerina-dev@googlegroups.com).
* Chat live with us via our [Slack channel](https://ballerina.io/community/slack/).
* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.
* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.
2 changes: 1 addition & 1 deletion teams/Ballerina.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ org= "ballerinax"
name= "microsoft.teams"
version= "0.1.1-SNAPSHOT"
authors = ["Ballerina"]
keywords = ["Microsoft", "Teams", "Communication"]
keywords = ["microsoft", "teams", "communication"]
repository = "https://github.com/ballerina-platform/module-ballerinax-microsoft.teams"
license = ["Apache-2.0"]

Expand Down
141 changes: 21 additions & 120 deletions teams/Module.md
View file
Original file line number Diff line number Diff line change
@@ -1,43 +1,20 @@
## Overview
Ballerina connector for Microsoft Teams is connecting to MS Teams platform API in Microsoft Graph via Ballerina
language easily. It provides capability to perform basic functionalities provided in MS Teams such as Sending messages,
Ballerina connector for Microsoft Teams is connecting to MS Teams platform API in Microsoft Graph via Ballerina language.
It provides capability to perform basic functionalities provided in MS Teams such as Sending messages,
Viewing messages, Creating Teams, Channels and Chats, deleting and updating resources etc programmatically.

This module supports [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/overview) v1.0 version.
## Configuring connector
### Prerequisites
- Microsoft Office365 Work or School account
- Access to register an application in Azure portal
This module supports [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/overview) `v1.0`.
## Prerequisites
Before using this connector in your Ballerina application, complete the following:

### Obtaining tokens
Follow the following steps below to obtain the configurations.

1. Before you run the following steps, create an account in [Microsoft Teams](https://www.microsoft.com/en-ww/microsoft-teams/group-chat-software). Next, sign into [Azure Portal - App Registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade). You should use your work or school account to register.

2. In the App registrations page, click **New registration** and enter a meaningful name in the name field.

3. In the **Supported account types** section, select **Accounts in this organizational directory only (Single-tenant)** or **Accounts in any organizational directory (Any Azure AD directory - Multi-tenant)**. Click **Register** to create the application.

4. Copy the Application (client) ID (`<CLIENT_ID>`). This is the unique identifier for your app.

5. In the application's list of pages (under the **Manage** tab in left hand side menu), select **Authentication**.
Under **Platform configurations**, click **Add a platform**.

6. Under **Configure platforms**, click **Web** located under **Web applications**.

7. Under the **Redirect URIs text box**, register the https://login.microsoftonline.com/common/oauth2/nativeclient url.
Under **Implicit grant**, select **Access tokens**.
Click **Configure**.

8. Under **Certificates & Secrets**, create a new client secret (`<CLIENT_SECRET>`). This requires providing a description and a period of expiry. Next, click **Add**.

9. Next, you need to obtain an access token and a refresh token to invoke the Microsoft Graph API.
First, in a new browser, enter the below URL by replacing the `<CLIENT_ID>` with the application ID.

- Here you need to provide a space seperated list of necessary scope names for `<SCOPES>`. The necessary scopes are shown below.
* Create a [Microsoft 365 Work and School account](https://www.office.com/)
* Create an [Azure account](https://azure.microsoft.com/en-us/) to register an application in the Azure portal
* Obtain tokens
- Use [this](https://docs.microsoft.com/en-us/graph/auth-register-app-v2) guide to register an application with the Microsoft identity platform
- The necessary scopes for this connector are shown below.

| Permissions name | Type | Description |
| ----------------------------- | --------- | ---------------------------------------------------------------- |
|:-----------------------------:|:---------:|:----------------------------------------------------------------:|
| Channel.Create | Delegated | Create channels |
| Channel.Delete.All | Delegated | Delete channels |
| Channel.ReadBasic.All | Delegated | Read the names and descriptions of channels |
Expand All @@ -54,57 +31,15 @@ First, in a new browser, enter the below URL by replacing the `<CLIENT_ID>` with
| Team.ReadBasic.All | Delegated | Read the names and descriptions of teams |
| TeamMember.ReadWrite.All | Delegated | Add and remove members from teams |
| TeamSettings.ReadWrite.All | Delegated | Read and change teams' settings |



```
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient&scope=<SCOPES> offline_access
```

10. This will prompt you to enter the username and password for signing into the Azure Portal App.

11. Once the username and password pair is successfully entered, this will give a URL as follows on the browser address bar.

```
https://login.microsoftonline.com/common/oauth2/nativeclient?code=xxxxxxxxxxxxxxxxxxxxxxxxxxx
```

12. Copy the code parameter (`xxxxxxxxxxxxxxxxxxxxxxxxxxx` in the above example) and in a new terminal, enter the following cURL command by replacing the `<CODE>` with the code received from the above step. The `<CLIENT_ID>` and `<CLIENT_SECRET>` parameters are the same as above.

```
curl -X POST --header "Content-Type: application/x-www-form-urlencoded" --header "Host:login.microsoftonline.com" -d "client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&grant_type=authorization_code&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient&code=<CODE>&scope=<SCOPES> offline_access" https://login.microsoftonline.com/common/oauth2/v2.0/token
```

The above cURL command should result in a response as follows.
```
{
"token_type": "Bearer",
"scope": openid <LIST_OF_SCOPES>",
"expires_in": 3600,
"ext_expires_in": 3600,
"access_token": "<ACCESS_TOKEN>",
"refresh_token": "<REFRESH_TOKEN>"
}
```

13. Provide the following configuration information in the `Config.toml` file to use the Microsoft Teams connector.

```ballerina
[ballerinax.microsoft.teams]
refreshUrl = <MS_REFRESH_URL>
refreshToken = <MS_REFRESH_TOKEN>
clientId = <MS_CLIENT_ID>
clientSecret = <MS_CLIENT_SECRET>
```


## Quickstart
## Create a Channel and send messages
### Step 1: Import MS Teams Package
First, import the ballerinax/microsoft.teams module into the Ballerina project.
To use the MS Teams connector in your Ballerina application, update the .bal file as follows:
### Step 1 - Import connector
Import the ballerinax/microsoft.teams module into the Ballerina project.
```ballerina
import ballerinax/microsoft.teams;
```
### Step 2: Configure the connection to an existing Azure AD app
### Step 2 - Create a new connector instance
You can now make the connection configuration using the OAuth2 refresh token grant config.
```ballerina
onedrive:Configuration configuration = {
Expand All @@ -117,9 +52,10 @@ onedrive:Configuration configuration = {
};
teams:Client teamsClient = check new (configuration);
```
### Step 3: Create a team
### Step 3 - Invoke connector operation

1. Create a team
```
teams:Team info = {
displayName: "<TEAM_NAME>",
Expand All @@ -133,43 +69,8 @@ if (newTeamId is string) {
} else {
log:printError(newTeamId.message());
}
```
### Step 4: Create a channel
```
string teamId = "<TEAM_ID>";
teams:Channel data = {
displayName: "<CHANNEL_NAME>",
description: "<CHANNEL_DESCRIPTION>",
membershipType: "standard"
};
teams:ChannelData|error channelInfo = teamsClient->createChannel(teamId, data);
if (channelInfo is teams:ChannelData) {
log:printInfo("Channel succesfully created " + channelInfo.id.toString());
log:printInfo("Success!");
} else {
log:printError(channelInfo.message());
}
```
### Step 5: Send message to channel
```
string teamId = "<TEAM_ID>";
string channelId = "<CHANNEL_ID>";
teams:Message message = {
body: {
content: "<MESSAGE>"
}
};

teams:MessageData|error channelMessage = teamsClient->sendChannelMessage(teamId, channelId, message);
if (channelMessage is teams:MessageData) {
log:printInfo("Message ID " + channelMessage.id.toString());
log:printInfo("Success!");
} else {
log:printError(channelMessage.message());
}
2. Use `bal run` command to compile and run the Ballerina program

```
## [You can find more samples here](https://github.com/ballerina-platform/module-ballerinax-microsoft.teams/tree/main/teams/samples)
**[You can find a list of samples here](https://github.com/ballerina-platform/module-ballerinax-microsoft.teams/tree/main/teams/samples)**
26 changes: 13 additions & 13 deletions teams/Package.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
Connects to Microsoft Teams from Ballerina
Connects to Microsoft Teams from Ballerina.

### Package Overview
The `ballerinax/microsoft.teams` is a [Ballerina](https://ballerina.io/) connector for Microsoft Teams.
This package provides the capability to easily access Microsoft Teams.
## Package overview
The `microsoft.teams` is a [Ballerina](https://ballerina.io/) connector for Microsoft Teams.
This package provides the capability to access Microsoft Teams.

#### Compatibility
| | Version |
|-------------------------------|-------------------------------|
| Ballerina Language Version | **Swan Lake Beta2** |
| API Version | **Microsoft Graph API v1.0** |
### Compatibility
| | Version |
|-----------------------|----------------------------|
| Ballerina Language | Ballerina Swan Lake Beta2 |
| Microsoft Graph API | v1.0 |

### Report Issues
To report bugs, request new features, start new discussions, view project boards, etc., go to the [Ballerina connector repository](https://github.com/ballerina-platform/module-ballerinax-microsoft.teams)
### Useful Links
- Discuss code changes of the Ballerina project in [ballerina-dev@googlegroups.com](mailto:ballerina-dev@googlegroups.com).
## Report issues
To report bugs, request new features, start new discussions, view project boards, etc., see [Ballerina connector repository](https://github.com/ballerina-platform/module-ballerinax-microsoft.teams)
## Useful links
- Discuss code changes of the Ballerina project via [ballerina-dev@googlegroups.com](mailto:ballerina-dev@googlegroups.com).
- Chat live with us via our [Slack channel](https://ballerina.io/community/slack/).
- Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag
Loading

0 comments on commit c38da3b

Please sign in to comment.