If you’ve spent any time with Trados Studio, you’ll know it’s quite simple to get things done — open the interface, click a few buttons, and you’re ready to go.  In Part 1 of this PowerShell trilogy, we introduced the Trados Studio PowerShell Toolkit, enabling project managers and localisation engineers to automate tasks without needing development skills.  GroupShare, while operating more behind the scenes, is no different in principle, except that we’ve never had a PowerShell toolkit for GroupShare before.  This meant that automating tasks was often left to professional developers or achieved through a more complex Business Management solution, which might have been more than what was needed for basic automation.

That said, Business Management systems certainly have their place.  They can provide the backbone for running larger operations and drive multiple Translation Management Systems when necessary.  However, I’ve also seen smaller businesses, just on the cusp of needing a larger solution, investing in tools whose features they only use a fraction of, when a simpler, more flexible approach might have been a better fit… had one been available!

A few years back, the Trados AppStore Team tried to make things easier by developing an Excel add-in—Excel4GroupShare—that allowed you to pull data out of GroupShare for reporting purposes.  That was useful, but it only solved half the problem.  Sure, you could extract all the data you wanted, but you couldn’t actually create or update anything in GroupShare.  It was like reading the contents of a filing cabinet without being able to add new files or make changes.  It was also very difficult, without considerable expertise, to get anything really useful from the reports, as the data wasn’t structured well since it was a direct pull from the database as opposed to being able to work with objects and their properties (remember those from Part 1?)

So this is where PowerShell comes in.  With the right toolkit, you can not only pull data from GroupShare, but also push it back — creating projects, managing users, and updating tasks — all without having to open GroupShare itself.  What’s more, the integration with the API ensures that almost everything you can do through the interface, you can now do from the command line.  And the best part?  You don’t need to be a developer to make it happen.  PowerShell lets you automate both sides of the process, making GroupShare as manageable as Trados Studio, but with the power of the server environment.

So, now that we’ve been introduced to PowerShell in the previous article (Part 1) we can jump straight to the scripts for GroupShare… almost!  I did mention that these articles are as much a part of my own learning journey as I hope they are for anyone reading them and this one is no different.  As I have been learning about PowerShell it’s clear that you don’t always need Modules to be able to write your scripts… so what are they, and could I, shopuld I, use them?

PowerShell Modules

First a quick reminder, in Part 1 I wrote this:

• Pre-built Commands: The PowerShell Toolkit comes with modules that contain pre-built commands (cmdlets).  These commands are specifically designed to interact with the Project Automation API.  Instead of writing code, you simply type these commands into the PowerShell terminal (as we did before) to perform tasks like creating projects, managing translation memories, or generating reports.
• Modules as Middlemen: The modules in the PowerShell Toolkit understand how to communicate with the API.  When you run a command in PowerShell, the module translates that command into something the API can understand and execute.  This way, you don’t need to know how the API works or how to program — PowerShell handles all of that for you.

In the GroupShare PowerShell Toolkit, which you can find here, it’s no different, and it comes with these modules:

• AuthenticationHelper
  • This script generates an authorisation token by signing in to a GroupShare server using provided credentials, which can be used for subsequent API calls to manage GroupShare resources.
• BackgroundTaskHelper
  • This script retrieves and manages GroupShare background tasks by providing options to filter, sort, and remove tasks using PowerShell and the GroupShare API, allowing project managers to automate task management without direct server access.
• ProjectServerHelper
  • This module provides various functions to interact with GroupShare via PowerShell, including project creation, file management, report generation, and status updates, allowing users to automate and manage tasks without needing to manually interact with the GroupShare interface.
• ResourcesHelper
  • This module provides functions for managing translation memories, project templates, termbases, field templates, and related operations, along with utilities for handling API requests and authorization.
• UserManagerHelper
  • The PowerShell module provides a set of functions for managing users, roles, organizations, permissions, and resources in a GroupShare server via its REST API.
• SystemConfigurationHelper
  • The PowerShell module provides functions to manage licensing, database servers, and containers in a GroupShare environment via its REST API.

Trados Studio had eight modules (the Studio API is actually a lot more complex than the REST API for GroupShare), GroupShare has six modules and of course they are also somewhat different to reflect the environment you are working in when dealing with GroupShare… which is an on-premise Server solution and not something running on your local computer.  I also made reference to the REST API quite a bit, but rest assured that this is all taken care of with the code in these modules so all you need to do is write PowerShell!

So that’s what the modules are for in the GroupShare PowerShell Toolkit.  But I want to expand on the concept of modules a little in general, so a broader explanation might be that a PowerShell module is like a toolbox that stores reusable scripts and functions, making them easier to use and share.  So instead of running individual scripts every time you need them, a module lets you group them together in one place, so they’re always available when you need them.  This could be especially useful if you perform the same tasks regularly.

ok – for me this is a bit closer to home.  When working on the Trados Studio scripts I was using the same 40-50 lines at the beginning of each script and these could surely have been added to a module instead.  So it made sense to me that I look at this since the requirements for just logging into GroupShare add more typing than the 40-50 lines I had before just to authenticate.

What would go in my Module?

There are basically three things I have to do every time I use PowerShell for GroupShare:

1. provide user credentials to be able to login to the server
2. import the GroupShareModules that are provided with the Toolkit
3. generate an authentication token from the provided user credentials so that my scripts can “talk” through the REST API

All of these things are clear in the sample script on the Github site that handles these things, and a few niceties around colours, descriptions and ensuring a clean screen, in the first 34 lines.  For my scripts, because I don’t want to work with this direct and simplified approach, especially the user credentials part where three parameters need to be pushed through the script every time, I think they’ll be longer and not just like this (because I don’t want to have to manually enter these credentials each time or put them into the script itself):

$server = "https://{your_groupshare_server}.com/" # Change this with your actual Groupshare server
$userName = "{your_username}" # Change this with your actual username
$password = "{your_password}" # Change this with your actual password

So, I think this would be a good example of how I can use a module to simplify my scripts… at least it’s a good example for me to have a go!

But before I do that let’s just answer the question of what I might use these scripts for?

Example usecases

Here are a few ideas to give you some indication of the usefulness… don’t forget you don’t need to enter GroupShare via the UI at all for this… it’s all command line driven:

• Automate User Management: Create, update, or delete users and assign roles across different organisations or projects.
• Manage Licences: Retrieve and monitor GroupShare licensing information automatically.
• Database Server Management: Create, update, or remove database servers that host translation memories (TMs) within GroupShare.
• Container Management: Create, modify, or delete TM containers within specific organisations to manage translation memory assets.
• Organise Translation Memory Resources: Move or link containers and resources between organisations to streamline TM sharing and organisation.
• Automate Permissions and Roles: Assign or update user roles and permissions to ensure proper access control for various resources across GroupShare.
• Create and Manage Projects: Automate the creation of new translation projects and assign them to specific teams or organisations.
• Automate File Uploads: Script the uploading of translation files and resources to specific projects or containers, reducing manual effort.
• Track Project Status: Retrieve and monitor the status of ongoing translation projects, ensuring up-to-date progress tracking.
• Assign Tasks to Users: Automatically assign translation or review tasks to users based on their roles or project involvement.
• Download Completed Translations: Automate the download of completed translations from GroupShare, streamlining the handoff process
• Generate Reports: Script the generation of project-specific reports, such as word counts, file statuses, or completion percentages, to facilitate project management oversight and even the import into other systems, detailed data on project resources to make it easier to keep a clean ship!
• etc…

I’m sure, if you are a GroupShare user, or an admin managing users, projects, resources, reports etc. that these will resonate with you and you’ll have at least a few more.  It could be that just one could be enough to make your day!  Using PowerShell makes it easy for you to see details about the resources in GroupShare that may not even be visible in the UI, yet are important for you in managing the overall system.

The sample script on the Github site contains a few things bundled into one script to give you a better idea of how this all works.  It can be easily run and it goes through these steps:

1. List the first 10 containers on the GroupShare server.
2. List the first 10 organizations on the server.
3. Create a new container in the root organization or retrieve an existing one.
4. List the first 10 users in the system.
5. Create a new user or retrieve an existing user if already present.
6. List the first 10 Translation Memories (TMs) on the server.
7. Create a new Translation Memory or retrieve an existing one.
8. Create a new project template using the newly created Translation Memory.
9. Create a sample text file to use for project creation.
10. Schedule the creation of a new project using the sample file and project template.
11. Clean up by removing all the loaded modules from the current PowerShell session.
12. Confirm script completion with a final message.

In itself quite useful and provides a great starting point for you when you get setup and start creating your own scripts.

A multifarious twist

But I want to come back to the things I did to get a better understanding myself.  So let’s start off with the idea of creating a new module, and as a reminder we’re talking about these things.

1. provide user credentials to be able to login to the server
2. import the GroupShareModules that are provided with the Toolkit
3. generate an authentication token from the provided user credentials so that my scripts can “talk” through the REST API

The use of user credentials is a new requirement compared to Trados Studio, where they aren’t necessary.  With GroupShare, user credentials and a server address are essential for authenticating and securely connecting to the server to access and manage its resources.  Additionally, credentials allow flexibility to log in to different GroupShare instances or assume different roles or email identities.  To achieve this, you’ll need three key pieces of information for each instance or role:

1. server url
2. username
3. password

User Credentials

Since I am basically lazy and intend to store user credentials on my computer somewhere so I can retrieve them easily I want to at least ensure they are secure.  Fortunately for me PowerShell has built in cmdlets for this very purpose called the Export-CliXml and Import-CliXml cmdlets.  These cmdlets can securely store and retrieve sensitive data, such as credentials, by leveraging the Windows Data Protection API (DPAPI), which ensures that the encrypted data can only be decrypted by the same user and machine that encrypted it.  Perfect!

My script to add the user credentials does a few simple things:

• prompts for the dataset name
• prompts for the GroupShare server url
• prompts for the user credentials (username and password)
• creates a custom object to store my dataset (we discussed objects in Part 1)
• exports this dataset to an encrypted XML file

All that might sound complicated but it’s really not thanks to the Export-CliXml cmdlet.  When I call the script, which you can find here, it runs like this:

After entering the aforementioned information I now have an encrypted XML file stored safely on my computer which I can use to easily recall the credentials when I want to login to a GroupShare server.  In case you don’t try this yourself, the example file shown below demonstrates how the data is structured.  Note that the 8-character password I entered is securely encrypted to ensure its confidentiality:

To recall these credentials all I need to do is use the Import-CliXml cmdlet in my script.  So if I wanted to get this example I created above I would use this:

$credentials = Import-CliXml -Path "C:\Users\paul\Documents\Production Scripts\Powershell\GroupSharePowershellToolkit\CredentialStore\myGroupShareServer-Credentials.xml"

This creates an object for me that contains the information in my dataset so I can use it.  For example:

• my dataset name: $credentials.DatasetName
• my GroupShare server url: $credentials.ServerUrl
• my credentials: $credentials.Credential

The  $credentials.Credential is also an object, but a special kind of object referred to as a PSCredential object.  This is a specialised type of object in PowerShell designed to securely store and manage user credentials encapsulating both the username and password in a secure and structured way.  If you want to test this a little I also created a simple script to retrieve the credentials you have saved which I also added to my github site here.

When you run that simple script on the same machine that encrypted the file originally it decrypts the password from the XML:

Now that I have this I can create my module to take care of these things:

1. provide user credentials to be able to login to the server
2. import the GroupShareModules that are provided with the Toolkit
3. generate an authentication token from the provided user credentials so that my scripts can “talk” through the REST API

GroupShareToolkit Module

I called my module GroupShareToolkit to align it with the name of the overall toolkit, although in hindsight I wish I’d given this more thought and used a different name just to avoid confusion with the overall toolkit created by the Trados AppStore Team… but as I mentioned already, I’m basically lazy and now I have everything working I’m not going to go back and change it now!

So, we know what user credentials are, we also understand about importing modules as this was well discused in Part 1… this just leaves generating an authentication token.  Authentication is required because the GroupShare server restricts access to its resources and APIs to ensure that only authorised users can perform operations.  This helps protect sensitive information, prevent unauthorised actions, and maintains the security of the system.  More specifically, authentication does this:

1. Confirms Your Identity: Verifies that you are a valid user with the correct username and password.
2. Grants Access Permissions: Ensures you only have access to resources and operations you are authorised to use (defined by your role in GroupShare).
3. Provides an Access Token: Once authenticated, you receive an access token that you use to interact with the API for subsequent operations.  This avoids the need to re-enter your credentials for every request.

So the three pre-built commands (cmdlets) I created for my module will be these:

1. Get-Credentials:
   • Opens a file dialog to select an encrypted XML file.
   • Retrieves credentials and server information from the file.
   • Outputs a PowerShell object with credentials and server details.
2. Import-GroupShareModules:
   • Loads specified GroupShare PowerShell modules.
   • Searches for modules in the script’s directory or a fallback directory.
   • Logs the status of each module (success, not found, or failed).
3. Connect-User:
   • Authenticates a user with the GroupShare server.
   • Uses a provided server URL and credentials.
   • Returns an authentication token for subsequent API requests.

You can find my module here – GroupShareToolkit

I’m not going to go into this in any more detail other than to explain that each module of the PowerShell Toolkits that the Trados AppStore Team created are made up of two files, a .psd1 (PowerShell Data) and .psm1 (PowerShell Module) file.  You can get by with just a .psm1 for basic use, but adding a .psd1 makes the module more robust, maintainable, and user-friendly.  For larger or shared modules, it’s considered best practice to include a .psd1 and who am I to argue with Jeffrey Snover!  So I created them as well.

1. .psm1 file (Module Script):
   • Contains the actual PowerShell code (functions, cmdlets, etc.).
   • This is where the logic and functionality of the module is written.
   • Think of it as the contents of a toolbox (tools and instructions).
2. .psd1 file (Module Data… or Manifest):
   • Acts as a configuration file for the module.
   • Specifies metadata about the module, such as:
     • Name, version, author, description.
     • Dependencies or required PowerShell versions.
     • Functions or cmdlets to expose to users.
   • Helps PowerShell load the module correctly and understand its capabilities.
   • Think of it as a label on the toolbox, describing what’s inside and how to use it.

Here’s where you can find them:

PowerShell Module: GroupShareToolkit.psm1

PowerShell Data: GroupShareToolkit.psd1

What have I created with all of this?

First of all I initiate all the scripts I created using the same AutoHotKey script to always use the appropriate version of PowerShell depending on what the script was for that I created in Part 1.

I then called my GroupShareToolkit module to prepare a PowerShell session for making authenticated requests to the GroupShare server, using dynamically loaded modules for various tasks.  These tasks are all based on a bunch of scripts to tackle a few things I thought might be useful in the context of working with GroupShare, but I won’t go into huge detail here other than to provide the links if you’re interested.  Hopefully you’ll find the scripts and accompanying README documentation sufficient to explain what they do.  Here’s the links:

• PowerShell Script Runner
• mAT_GroupShare_Powershell

Hopefully you’ll find the scripts useful and can view them as additional samples in case you wanted to take a similar approach.  This is what I created and I recorded a short video below to show you how a couple of them work… and perhaps explain further how useful these toolkits can be for a busy Localization engineer:

• 00_groupshare-get-help.ps1
• 01_Add Credentials.ps1
• 01_Retrieve Credentials.ps1
• 02_Sample_Features.ps1
• 03_Orgs_Containers_TMs.ps1
• 04_properties_of_container_and_TM_from_Org.ps1
• 05_users_by_organization.ps1
• 06_user_properties.ps1
• 07_Projects_by_Organization.ps1
• 08_addUser_to_Org.ps1
• 09_project_phase_users.ps1
• 10_create_Project_by_Template.ps1

The first one, on getting help, I created early on when I was building and testing as it sets me up to be able to start using the commands for all the modules.  I just left it there as it might be interesting if you want to get-help but nothing else.

Duration: 15 mins 17 seconds

Oh yes… and did I mention that I still have no idea how to script in PowerShell or AutoHotKey on my own… unless it’s really basic?  I did the majority of this with a little knowledge about what I wanted to achieve and the help of ChatGPT… so you can do it too!