GroupShare – Powershell Trilogy Part 2

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:

A PowerShell terminal displays a session where the user is prompted to enter the name for a credentials dataset, the GroupShare server URL, and credentials (username and password). After inputting the information, a message confirms that the credentials and server URL have been securely saved to an XML file at a specified path.

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:

A text editor displays the contents of an XML file named myGroupShareServer-Credentials.xml. The XML includes an object (<Obj>) with properties for DatasetName, Credential, and ServerUrl. The Credential property contains an encrypted password and a username, while the ServerUrl points to https://myGroupShareServer.com. The file uses the PowerShell XML schema for serialised objects.

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:

A PowerShell terminal displays the output of a script that successfully retrieves stored credentials. It displays: Dataset Name: myGroupShareServer Server URL: https://myGroupShareServer.com UserName: myemail@somedomain.com Password: password The script confirms the successful retrieval of credentials and concludes at the PowerShell prompt.

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:

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!

Trados Studio – Powershell Trilogy Part 1

An image representing the Trados Studio PowerShell Toolkit, featuring a stylised logo that merges the Trados Studio icon with the PowerShell icon. The main icon, prominently displaying a white 'S' over a dark blue and black triangle, symbolises the Trados Studio Toolkit. Above it, smaller icons with the letters 'G' and 'T' in turquoise and grey respectively, represent forthcoming toolkits for GroupShare and Language Cloud, hinting at a trilogy of PowerShell tools.It’s been 11-years since I have written about the PowerShell Toolkit that was originally created by the development team in SDL.  Back then I was able to fumble my way through setting it up, editing a few files, and automating the creation of a project in Trados Studio.  In all the time since then it’s not really received any updates, although there have been a couple of notable events.  First it was open-sourced in 2014 and then… well OK, only one notable event!  The PowerShell Toolkit has actually not been touched in all of this time to any great extent much to the consternation of some localization engineers who would have liked to have seen more work done to improve its capabilities.  In case you might wonder what use this Toolkit is… a brief explanation would be that it allows users to automate tasks that could be carried out in Trados Studio without the need for complex code development and without having to open Trados Studio at all!.  The toolkit makes use of the PowerShell task automation framework, which is already integrated into Windows, making it accessible to users who might not be familiar with software development.  The Trados Studio PowerShell Toolkit enables users to perform a variety of automated tasks, such as creating Translation Memories, setting up new projects, and generating project packages for different languages.

Continue reading “Trados Studio – Powershell Trilogy Part 1”

You can take a CAT to water!

A cartoon cat in spectacles sits by a riverbank, intently working on a laptop, conveying a blend of nature and technology. He's not drinking!

The phrase “You can lead a horse to water, but you can’t make it drink” emphasises the idea that you can offer opportunities or advantages to someone, but you can’t force them to take action if they’re unwilling. This proverb has deep historical roots, with its first recorded use in Old English around 1175, and it has been in continuous use ever since. It’s often used to illustrate the limits of influence and the importance of individual choice, making it applicable in various contexts, from personal relationships to business settings.

Continue reading “You can take a CAT to water!”

AI and Community

An image representing a modern, digital flat icon symbolizing an AI-supported community. It integrates elements of technology and symbols of community and unity, with a futuristic color scheme of blues and greens.I’ve written quite a few articles in the last year or so on the use of AI in a localization setting, and in general as a tool to help you complete technical tasks you may not have been able to do without help until now.  Certainly I’ve been making extensive use of this technology to simplify my life in many ways since I can now achieve in a few minutes things I could only wish I had time to learn until now.  But I thought I’d share a little of the practical use of AI within a community setting as we’ve made great use of this technology to help our users in the RWS Community and I think it largely goes unnoticed.

Continue reading “AI and Community”

Working with CSV’s…

Icon of a CSV file with a pencil, indicating a file used for entering or editing comma-separated values. The icon is designed to resemble a physical document with lines of text and the CSV extension in the upper right corner, encapsulated in a blue rounded square with a slight shadow effect.CSV, or files with “comma separated values”, is a simple format that everyone should be able to handle.  Certainly you’d think so except nothing is ever that straightforward and if you’ve ever spent time trying to work with these files and having to deal with all the problems inherent to this format then you’ll know exactly what I’m talking about.  In our industry, localization, the number of problems can even increase because we also have to deal with converting the content from one language to another.  I also wondered if there is a standard for CSV and the closest things to one is more of a recommendation, called RFC 4180.  It doesn’t seem to have been updated since 2005 and doesn’t take account of many of the problems that can be caused by not managing these files carefully.

So what sort of things are we talking about?  Here’s a few…

Continue reading “Working with CSV’s…”

The PerfectMatch…

mage: A heart made of puzzle pieces with a piece missing.In the world of translation, Trados Studio’s PerfectMatch feature is like the overachieving student who always gets straight A’s, and its academic partner is the brilliant but slightly disorganised professor.  PerfectMatch, with its meticulous and precise matching capabilities, often finds itself patiently sorting through the professor’s vast but somewhat chaotic repository of knowledge.  Picture PerfectMatch as the diligent student, poring over texts late into the night, determined to find that one perfect translation match.  Meanwhile, the academic partner is the genius who wrote the book on translation but can’t quite remember where they put it. Together, they form an unlikely but unstoppable duo – the PerfectMatch feature meticulously cross-referencing every word while the academic partner brings a wealth of knowledge, albeit sometimes hidden under a pile of papers.  It’s a partnership where precision meets wisdom, creating translations that are not just accurate, but also enlightened!

Continue reading “The PerfectMatch…”

Back to school… again!

The image depicts a stylised portrait of a person wearing academic attire. The individual has a neatly trimmed beard and moustache, and they are wearing a blue graduation cap with a tassel on the right side. They appear to be smiling contentedly, with their eyes closed in a serene expression. The figure's graduation gown is dark blue, and they are wearing a white shirt with a green tie underneath. The image has a clean and modern vector art style, with flat colours and simple shapes for features.After I did my last studies, apart from all the endless mandatory HR type training we have to endure these days, I thought that would be it for any sort of formal training for me.  In fact the main reason for me doing my last formal studies, TCLoc Masters degree at the University of Strasbourg, was to fill the gaps I thought I had given a complete lack of education in the field I’ve been working for the last 17-years.  That degree was very useful and I definitely learned a lot and filled some gaps, but whilst there was an element of technical localization to it I think it only scratched the surface and didn’t really cover the sort of skills that I think are needed, not just for localization engineers, but also for professional translators and project managers, working in technical localization today.

Continue reading “Back to school… again!”

XML… unravelling chaos

Image of a ball of wool unravelling around the letters XMLWhilst I would definitely not claim to be an expert, writing this blog has allowed me to learn a reasonable amount about XML over the years.  Most of the articles I’ve written have been about explaining how to manage the many amazing features in the filetypes that are supported by Trados Studio… and of course how to deal with the many changes over the years as the filetypes have become more and more sophisticated catering for the demands of our customers and the changes in the technologies applied to XML in general.  The result of these changes has led to some… let’s say… less than user friendly interfaces and features and you’d certainly be forgiven if you thought things were becoming a little chaotic!

Continue reading “XML… unravelling chaos”

Working under a cloud!

Image of a cloud of a thunderstorm with rain.In the heart of LingoVille, translator Trina was renowned for her linguistic prowess but was a bit behind in the tech world.  When her old typewriter finally gave out, she received a sleek new laptop, which came with OneDrive pre-enabled.  Initially hesitant about this “cloud magic,” she soon marvelled at the convenience of securely storing her translations online, accessible from anywhere, safeguarding her precious work from life’s unpredictabilities. This modern twist turned Trina from a tech-sceptic into a cloud enthusiast overnight.

And then she woke up!!

Continue reading “Working under a cloud!”

Going, going…. gone!

@paulfilkin twitter profile imageIt may be a little small to read but my social highlights for twitter  were:

      • joined in July 2010
      • tweeted 24.3K times
      • follow 16 users
      • followed by 1878 users

With the exception of youtube twitter was the only social media account I had retained.  youtube is more of a place to host and share videos and less of a platform I have to visit for anything else, so my exposure to the material in there is limited.  Twitter on the other hand… I can’t bring myself to call it X which is one of the most stupid marketing decisions I have seen in years… was a tool I liked to use because through tweetdeck I could easily filter out the nonsense and only be exposed, pretty much, to what I wanted to see.

Continue reading “Going, going…. gone!”