Publish version 0.1

DataOne · Mar 17, 2017 · 9aabbc1 · 9aabbc1
1 parent d06e311
commit 9aabbc1
Show file tree

Hide file tree

Showing 56 changed files with 3,200 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -0,0 +1,59 @@
+      ######################################################################
+     ##  __     __                                 _____ _          _ _    ##
+    ##   \ \   / /                                / ____| |        | | |    ##
+    ##    \ \_/ /_ _ _ __ ___  _ __ ___   ___ _ _| (___ | |__   ___| | |    ##
+    ##     \   / _` | '_ ` _ \| '_ ` _ \ / _ \ '__\___ \| '_ \ / _ \ | |    ##
+    ##      | | (_| | | | | | | | | | | |  __/ |  ____) | | | |  __/ | |    ##
+    ##      |_|\__,_|_| |_| |_|_| |_| |_|\___|_| |_____/|_| |_|\___|_|_|    ##
+     ##                                                                    ##
+      ######################################################################
+
+# YammerShell
+
+YammerShell is a Windows PowerShell module to access Yammer with PowerShell. It uses Yammer's REST API.  
+  => therefore authentication via OAuth is required.
+
+The contained CommandLets cover the most important endpoints provided by the API.
+
+
+## Importing the module
+
+1. Unpack the zip file.
+2. Open Windows PowerShell.
+3. Navigate to the directory with the unpacked files with `cd <path>`.
+4. Type `Import-Module .\YammerShell.dll`.
+
+
+## How to get authenticated
+
+* Yammer API needs a registered application to access its endpoints.
+* An application has a Bearer Token assigned.
+* Using this token YammerShell has the same rights the user that created the app has.
+
+--> The CmdLet `Get-YmToken` helps you to register an application in Yammer.  
+   _(**Warning**: to delete an app you have to contact the support!)_
+
+To use the token of a registered app, type `Set-YmToken <token>`.
+
+
+## How to use YammerShell
+
+After you registered an app and obtained a token,
+you can simply start YammerShell using the batch file [_StartYammerShell.bat](doc/_StartYammerShell.bat).
+
+It contains the following line where you have to change
+1234 to your token and <path> to the path where YammerShell.dll is located:
+
+```Batchfile
+start powershell -NoExit -NoLogo -Command "Import-Module '<path>\YammerShell.dll'; Set-YmToken '1234';`
+```
+
+To get a list of all CmdLets type `Get-YmHelp`. Also all available CmdLets are [documented on github](doc/README.md).
+
+
+## Errors
+
+If you use YammerShell-CmdLets in a script it may happen that an error occurs while performing many actions in a short period.
+This is caused by Yammer's API which has some [limitations of requests](https://developer.yammer.com/docs/rest-api-rate-limits).
+
+To fix it just add a small delay (e.g. with the CmdLet `Start-Sleep`) in your script to prevent too many requests.
diff --git a/doc/AddYmGroupMembership.md b/doc/AddYmGroupMembership.md
@@ -0,0 +1,45 @@
+# Add-YmGroupMembership
+
+Adds a user to a group specified by ID or email. If both is omitted the user that is currently authenticated will be added to the group
+
+## Syntax
+
+```PowerShell
+Add-YmGroupMembership [-GroupId] <int> [-UserId <int>]
+```
+
+```PowerShell
+Add-YmGroupMembership [-GroupId] <int> [-Email <String>]
+```
+
+## Parameters
+
+Parameter | Type | Required | Description
+----------|------|----------|------------
+GroupId   | int  | true     | The ID of the group where to add the user.
+UserId    | int  | false    | The ID of the user to add.
+Email     | String | false  | The email of the user to add. If the email does not correspond to an existing user then the user will be invited to join the network (if you are network admin).
+
+
+## Examples
+
+### Example 1
+
+```PowerShell
+PS:> Add-YmGroupMembership -GroupId 1234567
+```
+Adds the currently authenticated user to the group with the ID 1234567
+
+### Example 2
+
+```PowerShell
+PS:> Add-YmGroupMembership 1234567 -UserId 1213141516
+```
+Adds the user with the ID 1213141516 to the group with the ID 1234567
+
+### Example 3
+
+```PowerShell
+PS:> Add-YmGroupMembership 1234567 -Email user@company.com
+```
+Adds the user with the email _user@company.com_ to the group with the ID 1234567 or sends an invitation if user is not yet registered on yammer.
diff --git a/doc/AddYmRelationship.md b/doc/AddYmRelationship.md
@@ -0,0 +1,34 @@
+# Add-YmRelationship
+
+Add an org chart relationship for a user.
+
+## Syntax
+
+```PowerShell
+Add-YmRelationship [-UserId <int>] [-Subordinates <String[]>] [-Superiors <String[]>] [-Colleagues <String[]>]
+```
+
+## Parameters
+
+Parameter | Type | Required | Description
+----------|------|----------|------------
+UserId    | int  | false    | The ID of the user to add the relationship to. If not specified the currently authenticated user gets used.
+Subordinates | String[] | false | An array of email addresses of yammer users that are subordinates of the user specified by ID
+Superiors | String[] | false | An array of email addresses of yammer users that are superiors of the user specified by ID
+Colleagues | String[] | false | An array of email addresses of yammer users that are colleagues of the user specified by ID
+
+## Examples
+
+### Example 1
+
+```PowerShell
+PS:> Add-YmRelationship -UserId 1213141516 -Subordinates @('user@company.com')
+```
+Create a relationship for the user with the ID 1213141516 where the user with the email _user@company.com_ is a subordinate.
+
+### Example 2
+
+```PowerShell
+PS:> Add-YmRelationship -Superiors @('user1@company.com') -Colleagues @('user2@company.com', 'user3@company.com')
+```
+Create a relationship for the currently authenticated user where the user _user1@company.com_ is a superior and the users _user2@company.com_ and _user3@company.com_ are colleagues.
diff --git a/doc/GetYmGroup.md b/doc/GetYmGroup.md
@@ -0,0 +1,38 @@
+# Get-YmGroup
+
+Returns all groups or a specific group selected by id.
+
+## Syntax
+
+```PowerShell
+Get-YmGroup [[-Id] <int>]
+```
+
+## Returns
+
+> YammerShell.YammerObjects.YammerGroup
+> YammerShell.YammerObjects.YammerGroup[]
+
+
+## Parameters
+
+Parameter | Type | Required | Description
+----------|------|----------|------------
+Id        | int  | false    | The ID of a group to return.
+
+
+## Examples
+
+### Example 1
+
+```PowerShell
+PS:> Get-YmGroup
+```
+Returns all groups of the yammer network.
+
+### Example 2
+
+```PowerShell
+PS:> Get-YmGroup 1234567
+```
+Return the group with the ID 1234567
diff --git a/doc/GetYmHelp.md b/doc/GetYmHelp.md
@@ -0,0 +1,27 @@
+# Get-YmHelp
+
+Shows a list of all Yammer-CmdLets.
+
+## Syntax
+
+```PowerShell
+Get-YmHelp [-Force]
+```
+
+## Returns
+> String
+
+## Parameters
+
+Parameter | Type | Required | Description
+----------|------|----------|------------
+Force     | SwitchParameter | false | Try to force YammerShell to help you.
+
+## Examples
+
+### Example 1
+
+```PowerShell
+PS:> Get-YmHelp
+```
+Return a string with all YammerShell-CmdLet names and a short descripton.
diff --git a/doc/GetYmMessage.md b/doc/GetYmMessage.md
@@ -0,0 +1,106 @@
+# Get-YmMessage
+
+Shows messages of the user's Yammer network.
+
+
+## Syntax
+
+```PowerShell
+Get-YmMessage [-Id] <int>
+```
+
+```PowerShell
+Get-YmMessage -Sent [-Limit <int>] [-OlderThan <int>]
+```
+
+```PowerShell
+Get-YmMessage -Received [-Private] [-Limit <int>] [-OlderThan <int>]
+```
+
+```PowerShell
+Get-YmMessage -Topic <int>
+```
+
+```PowerShell
+Get-YmMessage -Top -Following
+```
+
+```PowerShell
+Get-YmMessage -Top
+```
+
+```PowerShell
+Get-YmMessage -Following
+```
+
+## Returns
+
+> YammerShell.YammerObjects.YammerMessage
+> YammerShell.YammerObjects.YammerMessage[]
+
+
+## Parameters
+
+Parameter | Type | Required | Description
+----------|------|----------|------------
+Id        | int  | false    | The ID of a message to get.
+Sent      | SwitchParameter | false | Only sent messages get returned if set.
+Limit     | int  | false    | The Maximum of returned messages.
+OlderThan | int  | false    | The ID of a message. Specify this to return messages older than this message.
+Received  | SwitchParameter | false | All received messages get returned if set.
+Private   | SwitchParameter | false | Set this to receive only private messages.
+Topic     | SwitchParameter | false | The ID of a specific topic.
+Top       | SwitchParameter | false | Return top messages if set.
+Following | SwitchParameter | false | Return messages you follow if set.
+
+
+## Examples
+
+### Example 1
+
+```PowerShell
+PS:> Get-YmMessage -Id 806862287
+```
+Return the message with the ID 806862287.
+
+### Example 2
+
+```PowerShell
+PS:> Get-YmMessage -Received -Private -Limit 5
+```
+Return the first five received private messages of the authenticated user.
+
+### Example 3
+
+```PowerShell
+PS:> Get-YmMessage -Sent -OlderThan 806862287
+```
+Return messages sent by the authenticated user older than the message with the ID 806862287
+
+### Example 4
+
+```PowerShell
+PS:> Get-YmMessage -Topic 18629862
+```
+Return messages for the topic with the ID 18629862.
+
+### Example 5
+
+```PowerShell
+PS:> Get-YmMessage -Top -Following
+```
+Return the authenticated user’s message feed, based on the selection made between _Following_ and _Top_ conversations.
+
+### Example 6
+
+```PowerShell
+PS:> Get-YmMessage -Top
+```
+Return the algorithmic feed for the authenticated user that corresponds to _Top_ conversations. The Top conversations feed is the feed currently shown in the Yammer mobile apps.
+
+### Example 7
+
+```PowerShell
+PS:> Get-YmMessage -Following
+```
+Return the _Following_ feed which is conversations involving people, groups and topics that the authenticated user is following.
diff --git a/doc/GetYmNetwork.md b/doc/GetYmNetwork.md
@@ -0,0 +1,36 @@
+# Get-YmNetwork
+
+Returns a list of networks to which the current user has access to.
+
+
+## Syntax
+
+```PowerShell
+Get-YmNetwork [[-Id] <int>]
+```
+
+## Returns
+> YammerShell.YammerObjects.YammerNetwork
+
+## Parameters
+
+Parameter | Type | Required | Description
+----------|------|----------|------------
+Id        | int  | false    | The ID to filter the networks after.
+
+
+## Examples
+
+### Example 1
+
+```PowerShell
+PS:> Get-YmNetwork
+```
+Returns all networks to which the currently authenticated user has access to.
+
+### Example 2
+
+```PowerShell
+PS:> Get-YmNetwork 495653
+```
+Return the network with the ID 495653 if the authenticated user as access to it.
diff --git a/doc/GetYmToken.md b/doc/GetYmToken.md
@@ -0,0 +1,24 @@
+# Get-YmToken
+
+Navigates you through the pages which are needed to **create a new application** and to get the bearer token.
+Then it sets the received token. If you already registered an app you can set its token via [Set-YmToken](SetYmToken.md).
+
+## Syntax
+
+```PowerShell
+Get-YmToken
+```
+
+## Examples
+
+### Example 1
+
+```PowerShell
+PS:> Get-YmToken
+```
+
+This first opens the page to register an app in yammer.  
+Then it lets you paste the _client id_ and the _client secret_.  
+Next you get redirected and have to paste the _secret_ you will receive there.  
+Now the bearer token gets automatically requested and set for this session.  
+It is recommended to _save this token_ for next PowerShell sessions where you can set it with [Set-YmToken](SetYmToken.md).