moometric/gsuite

Simple PHP library to manage GSuite users signatures

1.0.3 2018-09-28 14:47 UTC

Requires

• php: >=5.3.0
• google/apiclient: ^2.0

MIT

• Moometric MooMaster

• api
• signature
• gmail
• gsuite

README

GSuite Signature Manager (PHP)

Ensure that all your users have a standard signature by updating them using the gmail API. Users signatures can be updated direct from the GSuite users directory using standard and custom fields or alternatively from a JSON users file.

• defaultSig.html template is included, you can add your own templates to the "signatures" directory.
• testUsers.json JSON file is included as an example when fetching users from local source rather than GSuite domain.
• Fetch users direct from GSuite directory including all attributes (Full name, phone number, profile photo, etc...).
• Support for auto fetching and mapping of GSuite directory custom attributes to merge tags for use in email signatures.

Getting Started

Prerequisites

• You are a GSuite domain admin with full super admin access
• Make sure your are running at least PHP 5.4+
• Your PHP server can read files from the local_vars and signatures directory (after installing)

Installing

Step 1: Create your service account

Ensure that you have gone through the steps described here to get your service-account.json file. More information can be found on the Google Admin SDK Guide to setting up a service account for your GSuite domain.

Copy your service-account.json file into the local_vars directory

Step 2: Grant Domain Wide Delegation

Ensure that you have granted domain wide delegation through the GSuite console for the following scopes of your service account

https://www.googleapis.com/auth/admin.directory.user', 'https://www.googleapis.com/auth/admin.directory.user.alias', 'https://www.googleapis.com/auth/admin.directory.userschema','https://www.googleapis.com/auth/gmail.settings.basic','https://www.googleapis.com/auth/gmail.settings.sharing

Step 3: Install or clone this repo

composer require moometric/gsuite

OR

git clone https://github.com/moometric/GSuiteSignatureManager.git

Step 4: Update your signature template

By default there is a signature template located in "signatures/defaultSig.html". You can modify this template and include your own MERGE fields.

Merge fields are in the following format {{mergeFieldOne}}. If you're not sure what merge fields you can use, use listMergeFields() function to view a list of available merge tags.

Step 5: Instantiate the signature object

If using composer, don't forget to include your autoload file.

require_once '/path/to/your-project/vendor/autoload.php';

use Moometric\mooSignature;
$mooSig = new mooSignature("primaryDomain.com", "[e-mail]");
// Optionally set the path where your default service-account.json file is stored.
$mooSig->addSettingServiceAccountPath("/your/project/path/local_vars/");
// Optionally set the path where your signatures are stored.
$mooSig->addsettingSignaturePath("/your/project/path/signatures/");

Testing

Included is an index.php file which contains a few tests to get started.

Once you go live, ensure that you switch off testing mode.

$mooSig->addSettingRunTestMode(False);

Usage Examples

Message of the day

Set/Update the MOTD for all GSuite users

This will set "Hello World" as the MOTD for all GSuite users

$mooSig->addSettingMOTDHTML("<span style=\"color: red;\">Hello World</span>");
$mooSig->addSettingMOTDPosition("Below");
$mooSig->addSettingMOTD(True);
$mooSig->setSignatureMOTD();

Removing the MOTD for all GSuite users

If exists, this will remove MOTD for all GSuite users

$mooSig->removeSignatureMOTD();

Set/Update/Remove MOTD for select GSuite users

If you only want certain GSuite users to have a MOTD, you can filter the users by their primary email.

$mooSig->addSettingMOTDHTML("<span style=\"color: red;\">Marketing Department MOTD</span>");
$mooSig->addSettingFilterEmailsToUpdate(["[e-mail]", "[e-mail]"]);
$mooSig->setSignatureMOTD();

Or remove MOTD from those same select users

$mooSig->removeSignatureMOTD();

Updating the signature

Update signature for all domain users

Update the signature for all domain users from the default template.

$mooSig->addSettingSetTemplate("defaultSig.html");
$mooSig->updateSignatures();

Update signature for all domain users and set MOTD

Update the signature for all domain users from the default template.

$mooSig->addSettingMOTDHTML("<span style=\"color: red;\">Hello World</span>");
$mooSig->updateSignatures();

Update signature for only certain users or single user

Update the signature for all domain users from the default template. In the example below only [e-mail] and [e-mail] will be updated, all other users will be excluded

$mooSig->addSettingFilterEmailsToUpdate(["[e-mail]", "[e-mail]"]);
$mooSig->updateSignatures();

Exclude users who don't have their profile photo set

Update the signature for all domain users but exclude those who don't have a profile photo or title set.

$mooSig->addSettingSkipConditions(["title", "thumbnailPhotoUrl"]);
$mooSig->updateSignatures();

Update signature for users in a JSON file

Update the signature for users in the JSON file testUsers.json.

$mooSig->addSettingUsersFile("testUsers.json");
$mooSig->updateSignatures();

Update signature for users in your own array

In this example only users who are in the array below will be updated with a new signature. Two users below will be updated.

$mooSig->addSettingUserArray([
	[
		"primaryEmail" => "[e-mail]", 
		"alias" => "[e-mail]", 
		"fullName" => "MooMaster",
	],
	[
		"primaryEmail" => "[e-mail]", 
		"alias" => "[e-mail]", 
		"fullName" => "MooMinor",
	]
]);
$mooSig->updateSignatures();

Other examples

See a list of available merge tags

If you want to see what merge fields are available for use in your template, you can run the following function to echo and output to your browser.

$mooSig->listMergeFields();

Output will look something like this

Merge Tag	Example
{{primaryEmail}}	[e-mail]
{{alias}}	[e-mail]
{{thumbnailPhotoUrl}}	http://i.imgur.com/mmvUt5x.png
{{fullName}}	MooMaster
{{phone0}}	555-555-555
{{title}}	IT Admin / Developer

Settings

Path Settings

If your signature, service-account.json or user defined JSON file aren't stored in the default directories, you can use the following to set the path where your files are located.

Set the service-account.json path (Default - /local-vars/)

Set the directory where your service-account.json file is stored

$mooSig->addSettingServiceAccountPath("/your/project/path/local_vars/");

Set the signatures path (Default - /signatures/)

Set the directory where your signatures are stored

$mooSig->addsettingSignaturePath("/your/project/path/signatures/");

Set the users file path (Default - /local-vars/)

Set the directory where your users json files are stored. This is only required if you are fetching your users from a local JSON file, rather than the GSuite directory.

$mooSig->addSettingJSONPath("/your/project/path/local_vars/");

Basic Settings

Run test mode (Default - True)

During test mode no signatures are updated

$mooSig->addSettingRunTestMode(True);

Preview the output HTML (Default - True)

When testing, echo the signature into your browser

$mooSig->addSettingPreviewSignature(True);

Get users from GSuite (Default - True)

Rather than JSON or other array. Default is True. Will default to False if you use specify a JSON array or another array source after this flag has been set.

$mooSig->addSettingGetUsersFromGsuite(True);

Set the template (Default - defaultSig.html)

you wish to use that is located in the subfolder "/signatures"

mooSig->addSettingSetTemplate("defaultSig.html");

Strip unused tags (Default = True)

that start and end with '{{' '}}' when generating the template. Switch to False when debugging.

$mooSig->addSettingStripBlanks(True);

User Filters

Skip fields (Default = [])

Skip updates if any of the fields are NULL, BLANK or don't exist. Useful when updating users that might have blank values that need to be updated before their signature is created. In the example below, we're skipping the signature update for users that don't have their title or profile picture set.

$mooSig->addSettingSkipConditions(["title", "thumbnailPhotoUrl"]);

Filter email addresses to update (Default = [])

Enter the primaryEmail addresses that you wish you update. Any emails that aren't included here won't be updated.

$mooSig->addSettingFilterEmailsToUpdate(["[e-mail]", "[e-mail]"]);

Unset all current filters

If filters have been applied, you can unset them all using the following. Useful if you're chaining a whole heap of bulk updates with many different changing filters

$mooSig->addSettingUnsetFilters();

MOTD Message of the day Settings

Set MOTD position (Default = "Below")

Set where the MOTD appears (Above or Below) on the signature.

$mooSig->addSettingMOTDPosition("Below");

Set HTML for MOTD (Default = "")

String value of the HTML that you want to include in the email signature.

$mooSig->addSettingMOTDHTML("<span style=\"color: red;\">Hello World</span>");

Set MOTD when generating template (Default = True)

If you don't set the MOTD HTML, this will have no effect. Otherwise when the template for a user is generated, the MOTD will be included upon generation.

$mooSig->addSettingMOTD(True);

Other Settings

Get users from array (Default = [])

If you would prefer to get the users details from an array rather than the GSuite directory, you can push your own custom users array along with all the details for the signatures you wish to update. For this option you must include the primaryEmail and alias in each user array.

$mooSig->addSettingUserArray([
	[
		"primaryEmail" => "[e-mail]", 
		"alias" => "[e-mail]", 
		"thumbnailPhotoUrl" => "http://i.imgur.com/mmvUt5x.png",
		"fullName" => "MooMaster",
		"phone0" => "555-555-555",
		"title" => "IT Admin / Developer"
	],
	[
		"primaryEmail" => "[e-mail]", 
		"alias" => "[e-mail]", 
		"thumbnailPhotoUrl" => "http://i.imgur.com/mmvUt5x.png",
		"fullName" => "MooMinor",
		"phone0" => "444-444-444",
		"title" => "DevOps Admin"
	]
]);

Get users from JSON file (Default = "")

If you would prefer to get the users details from a JSON file rather than the GSuite directory, you can add your JSON file to the /local_vars folder instead. For this option you must include the primaryEmail and alias in each JSON object.

$mooSig->addSettingUsersFile("testUsers.json");

Example JSON File

[
	{
		"primaryEmail": "[e-mail]",
		"alias": "[e-mail]",
		"thumbnailPhotoUrl": "http://i.imgur.com/mmvUt5x.png",
		"fullName": "MooMaster",
		"phone0": "555-555-555",
		"title": "IT Admin / Developer"
	},
	{
		"primaryEmail": "[e-mail]",
		"alias": "[e-mail]",
		"thumbnailPhotoUrl": "http://i.imgur.com/mmvUt5x.png",
		"fullName": "MooMinor",
		"phone0": "444-444-444",
		"title": "DevOps Admin"
	}
]

Authors

• MooMaster - initial work - Moometric.com

License

This project is licensed under the MIT License - see the LICENSE.md file for details