AptecoPSModules

The Apteco PowerShell Modules allow you to extend your current Apteco Marketing Stack with more customisation. For example here is fully featured Framework to create your own channels for Orbit and PeopleStage. Other modules in here are helpful in working with your data.

All modules are targeted to be published on PowerShell Gallery. So Installation is much easier than copy&paste.

Those are the already published packages, but more are in the pipeline:

Name	Type	Repository/Version	Platform	Downloads
AptecoPSFramework	Module
ConvertStrings	Module
ConvertUnixTimestamp	Module
EncryptCredential	Module
ExtendFunction	Module
InvokeWebRequestUTF8	Module
MeasureRows	Module
MergeHashtable	Module
MergePSCustomObject	Module
SyncExtractOptions	Script
WriteLog	Module
Install-Dependencies	Script
Import-Dependencies	Script
PSOAuth	Module
TestCredential	Module
PSNotify	Module
SqlPipeline	Module
OSMGeocode	Module

Here are some high level descriptions. Please follow the links from the table or go into the subdirectories to get more detailed information.

AptecoPSFramework

This framework is mainly created for installing and using custom channels in Apteco Orbit and PeopleStage. The channel implementations are written in PowerShell and already implemented as "Plugins" in this module. But there is a function implemented so you can refer to your own channels that are not getting overwritten if you update this module.

ConvertStrings

Allow you to manipulate strings like converting the string encoding or replacing strings. Random strings and hashed strings are also included.

MergePSCustomObject

This module merges two PSCustomObjects into one. It is able to handle nested structures like hashtables, arrays and PSCustomObjects.

ConvertUnixTimestamp

Converts a [DateTime] into a numeric unix timestamp as [UInt64] and vice versa.

To get a unix timestamp from a [DateTime]::Now or (Get-Date) just do it like in these examples

Get-Unixtime
Get-Unixtime -InMilliseconds
Get-Unixtime -InMilliseconds -Timestamp ( Get-Date ).AddDays(-2)

To convert a timestamp back, just do it like here

ConvertFrom-UnixTime -Unixtime 1591775090
ConvertFrom-UnixTime -Unixtime 1591775090 -ConvertToLocalTimezone
ConvertFrom-UnixTime -Unixtime 1591775146091 -InMilliseconds
( ConvertFrom-UnixTime -Unixtime $lastSession.timestamp ).ToString("yyyy-MM-ddTHH:mm:ssK")

EncryptCredential

This module is used to double encrypt sensitive data like credentials, tokens etc. They cannot be stolen pretty easily as it uses SecureStrings.

Execute commands like

"Hello World" | Convert-PlaintextToSecure

to get a string like

76492d1116743f0423413b16050a5345MgB8AEEAYQBmAEEAOABPAEEAYQBmAEYAKwBuAGQAegBxACsASQBRAGIAaQA0AEEAPQA9AHwANAAxAGEAYQBhADAAYwA3ADQAYwBiADkAYwAzADEAZgBkAGUAZQBkADQAOABhADIAMgA5AGUAMAAyADkANwBiADcAMQAyADgAOAAzADkAMwBiADAANAA0ADcAMwA3ADQANgAxADMAYwBmADQAZQAyADIAMwBkAGQAMQBhADUAMAA=

This string can be decrypted by calling

"76492d1116743f0423413b16050a5345MgB8AEEAYQBmAEEAOABPAEEAYQBmAEYAKwBuAGQAegBxACsASQBRAGIAaQA0AEEAPQA9AHwANAAxAGEAYQBhADAAYwA3ADQAYwBiADkAYwAzADEAZgBkAGUAZQBkADQAOABhADIAMgA5AGUAMAAyADkANwBiADcAMQAyADgAOAAzADkAMwBiADAANAA0ADcAMwA3ADQANgAxADMAYwBmADQAZQAyADIAMwBkAGQAMQBhADUAMAA=" | Convert-SecureToPlaintext

and get back

Hello World

ExtendFunction

This module can be used to extend existing functions/cmdlets with more scripting and possibly additional parameters like

function Invoke-CoreWebRequest {
    
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)][string]$AdditionalString
    )
    DynamicParam { Get-BaseParameters "Invoke-WebRequest" }

    Process {
        Write-Host $AdditionalString
        $updatedParameters = Skip-UnallowedBaseParameters -Base "Invoke-WebRequest" -Parameters $PSBoundParameters
        Invoke-WebRequest @updatedParameters
    }

}

InvokeWebRequestUTF8

Executes an Invoke-WebRequst, but converts the content afterwards into UTF8, if the correct encoding wasn't given back.

Install-Dependencies

A small script that helps you to install scripts/modules/packages you need to load via a repository like PowerShellGallery or NuGet or a local repository.

Just use

Install-Dependencies -Module "WriteLog" -LocalPackage "System.Data.Sqlite", "Npgsql" -Verbose

Import-Dependencies

A small script that helps you to import your installed modules and packages you have installed through PowerShellGallery, NuGet or a local repository.

Just use

Import-Dependencies.ps1 -Module "WriteLog" -LoadWholePackageFolder -Verbose

to load your lib subfolder or

Import-Dependencies.ps1 -Module "WriteLog" -LocalPackage "System.Data.SQLite", "Npgsql" -Verbose

to load specific folders

MeasureRows

Just use

Measure-Rows -Path "C:\Temp\Example.csv"

or

"C:\Temp\Example.csv" | Measure-Rows -SkipFirstRow

or

Measure-Rows -Path "C:\Temp\Example.csv" -Encoding UTF8

or even

"C:\Users\Florian\Downloads\adressen.csv", "C:\Users\Florian\Downloads\italian.csv" | Measure-Rows -SkipFirstRow -Encoding ([System.Text.Encoding]::UTF8)

to count the rows in a csv file. It uses a .NET streamreader and is extremly fast.

MergeHashtable

This module merges two Hashtables into one. It is able to handle nested structures like hashtables, arrays and PSCustomObjects.

MergePSCustomObject

This module merges PSCustomObjects into one. It is able to handle nested structures like hashtables, arrays and PSCustomObjects.

OSMGeocode

Geocode single or multiple addresses on the fly via OpenStreetMaps like

$addr = [PSCustomObject]@{"street" = "Schaumainkai 87";"city" = "Frankfurt";"postalcode" = 60589;"countrycodes" = "de"}
$addr | Invoke-OSM -Email "[email protected]" -AddressDetails -ExtraTags -ResultsLanguage "de"

PSOAuth

Support of oAuth v2 in PowerShell! This module allows the oAuth flow to create your first api token for Microsoft Dynamics, Salesforce, CleverReach and much more... We support redirect urls to local urls http://localhost:54321 and app urls (handled via registry) apttoken://localhost. The local url is instantly starting up a basic webserver on the port you have defined. This module can be used for debugging or server2server communication. Here you can see the two methods than can be used:

import-module PSOAuth -Verbose
$oauthParam = [Hashtable]@{
    "ClientId" = "ssCNo32SNf"
    "ClientSecret" = ""     # ask for this at Apteco, if you don't have your own app
    "AuthUrl" = "https://rest.cleverreach.com/oauth/authorize.php"
    "TokenUrl" = "https://rest.cleverreach.com/oauth/token.php"
    "SaveSeparateTokenFile" = $true
}
Request-OAuthLocalhost @oauthParam

or

import-module PSOAuth -Verbose
$oauthParam = [Hashtable]@{
     "ClientId" = "ssCNo32SNf"
     "ClientSecret" = ""     # ask for this at Apteco, if you don't have your own app
     "AuthUrl" = "https://rest.cleverreach.com/oauth/authorize.php"
     "TokenUrl" = "https://rest.cleverreach.com/oauth/token.php"
     "SaveSeparateTokenFile" = $true
}
Request-OAuthApp @oauthParam -Verbose

PSNotify

Use Telegram, Email, Teams and Slack to get notifications via commandline. This can be used to be notified when important things happen like successful campaigns or maybe occured problems. Different channels can be bound together as groups so you can send the same message through different channels.

SyncExtractOptions

This script is used to switch off or switch on some data sources in FastStats Designer to allow a build with only a few tables (like customer data) and then later do a bigger build with customer and transactional data.

This example just changes the behaviour of the extract options and saves it in the same xml

SyncExtractOptions -DesignFile "C:\Apteco\Build\20220714\designs\20220714.xml" -Include "Bookings", "People"

SqlPipeline

To allow easier import of data into databases like PostgreSQL, SQLite, MariaDB/MySQL, SQLServer, Oracle and more there is a pretty handy module named SimplySql. As this module does not support pipeline input yet, I have created this wrapper with high flexibility. So this module allows importing csv file import like

Import-Module SqlPipeline, SimplySql
Open-SQLiteConnection -DataSource ".\db.sqlite"
Measure-Command {
    import-csv -Path '.ac_adressen.csv' -Encoding UTF8 -Delimiter "," | Add-RowsToSql -TableName "addresses" -UseTransaction -Verbose
}
Close-SqlConnection

But there is much more. Just go to that subdirectory to view the README file.

TestCredential

This module helps you to test credentials before you use them. By default, this module asks 3x times before cancelling. It delivers a $true or $false back.

Use this module in interactive mode -> this one requests your user and password, uses the current user as default

Test-Credential

Define User and password beforehand

$c = Get-Credential
Test-Credential -Credentials $c

OR

$c = Get-Credential
Test-Credential -Credentials $c  -NonInteractive

OR

Get-Credential | Test-Credential

WriteLog

This script allows to write log files pretty easy without any fuzz. It retries the write commands if parallel processes want to write into the same logfile.

Execute commands like

Write-Log -message "Hello World"
Write-Log -message "Hello World" -severity ([LogSeverity]::ERROR)
"Hello World" | Write-Log

Then the logfile getting written looks like

20220217134552	a6f3eda5-1b50-4841-861e-010174784e8c	INFO	This is a general information
20220217134617	a6f3eda5-1b50-4841-861e-010174784e8c	ERROR	Note! This is an error
20220217134618	a6f3eda5-1b50-4841-861e-010174784e8c	VERBOSE	This is the verbose/debug information
20220217134619	a6f3eda5-1b50-4841-861e-010174784e8c	WARNING	And please look at this warning

separated by tabs.

Click on the folder for more information.