I decided I could do better. Firstly, she works for the NHS. I have a lot of respect for the NHS, but they are notoriously terrible at IT. So email was out – SMS seemed the best way to go with these guys.
Last year I wrote a script that gave me a list of names & numbers to text, which I then copied and pasted into my phone – total tedium.

This year I decided I should go one better, and have all the work done for me.
The prerequisites of using this are twofold.

Firstly, you must have an android phone, connected via USB to your PC, with debugging enabled and have ADB installed and available in powershell.
I used this guide and despite not having used ADB since I still had long luscious locks, found the process satisfyingly simple.
With that done, run ‘adb devices’ and so long as it lists a device you’re connected.

The second prerequisite is to not comment on my formatting/best practices in powershell; this is purely for a one off (until next year at least) and has done the job very nicely thank you.

Add each person/number you require, run the script and you should be away. The system should assign a person randomly, and avoid duplication or assigning a person to themselves.

function Create-Person {
    param(
        [string]$Name, [string]$Number
    )

    $Person = New-Object System.Object
    $Person | Add-Member -type NoteProperty -name Name -value $Name
    $Person | Add-Member -type NoteProperty -name Number -value $Number
    return $Person
}

function Send-SMS
{
    param([string]$Number, [string]$message)

    adb shell service call isms 7 i32 0 s16 "com.android.mms.service" s16 $Number s16 "null" s16 $message s16 "null" s16 "null"
}

$People = @()

$People += Create-Person Fred 07234555111
$People += Create-Person Colin 01712232098
$People += Create-Person 'Fred K' 07431987457
$People += Create-Person Susan 0794282342

$AvailablePeople = {$People}.Invoke()

foreach ($Person in $People)
{
    do {
        $RecipientNumber = Get-Random -Maximum $AvailablePeople.Count
    } while ($AvailablePeople[$RecipientNumber].Name -eq $Person.Name)
    $Recipient = $AvailablePeople[$RecipientNumber]
    $Message = 'For\ this\ years\ secret\ santa\ you\ are\ buying\ a\ gift\ for....' + $Recipient.Name
    Write-Host $Message '|' $Person.Name
    send-sms $Person.Number $Message
    $AvailablePeople.RemoveAt($RecipientNumber)
}

I mean, seriously, look at that – Almost everything I was trying to achieve, right within the product, a mere two keys away AND it matches on partial results. Egg is in proximity to my face.

There are some differences to the solution I suggested though, and this potential was recognised, picked up, and ran with by the preeminent @Waldo1001.
After some discussion on twitter, which you can see from here:

Waldo picked this up as an addition to his very handy CRS Extension for VS Code, and we also made a few tweaks the the regex. I thought I’d take the opportunity to explain those tweaks and how they work.

^\w+ (\d* )?"*
^\w+ (\d* )?"*(\w+ *)*

Firstly, Waldo suggested making the digit portion optional, which would allow this to search all object types including the ID-less ‘Interface’ objects.
To do this, we wrapped the digit portion in brackets to make it a group, then added a ? after the group to specify that the group must occur 0 or more times.

You may think ‘Why not just write make the number optional’, and if you did think that then you’re asking good questions.
However, you have to remember that the space characters are part of our pattern – in an object name such as:
table 27 Item
We have the pattern:
Word_Space_Number_Space_Word

If we remove that ID, we also remove a space character. Therefore we need to be looking for a combination of a number AND a space character together. Hence the group:

(\d+ ) 

Think of the group as a sub-regex within the bigger regex. We can now apply an operator to the group, rather than the individual operators, that specifies that group occurs zero or one times:

(\d+ )?

So now our regex will match ‘Table 27 Item’ as well as ‘interface “Price Calculation”‘
But wait!

We’ve gone back to matching far too many results.

The answer to that, lines in the fact that object names are always at the start of the file, and regular expressions have an operator that says ‘Look at the start of the file only’

Much better, eh?
So now, our regex looks like this:

^\w+ (\d+ )?"*

I have one more trick up my sleeve – what if you want to find objects where your word isn’t the first word in the name? What if when you search ‘Item’ you want to also return ‘Adjust Item Costs’?
We simply add at the end:

(\w+ *)*

This regex says to look for a group including a word and maybe a space, and to match 0 or more of those groups before our search term

This is effectively saying that after the double quote, which may or may not be there, also look for any number of, or none of, words, which themselves may or may not have a space after them, therefore allowing us to match things like ‘page 2314 “BC O365 Item List”‘ when we search for item

In closing, if you just want to quickly and easily search objects within VS Code, absolutely use Ctrl+P. However, if you want to learn regex, this isn’t a bad place to start. And if you want to be a bit more specific in what you search, or if object names don’t match object names for some reason, this may help.

However, finding that initial starting point can be a real pain – for example, if I want to use the global search function to find the item record I get this:
It’s a list of every time the word ‘Item’ is used, regardless of context, and results in more than 10k responses – too many to be useful.
I could of course write ‘Table 27 ‘ and it would return one result, the item table object. But even in the days of C/AL I never tried too hard to learn object IDs, I’m even less interested in knowing them now.

What I really want is to be able to perform a search for an object name, and only return objects.

What I really want is this:


This also works for all objects, such as the sales header:

Or maybe I’d like the sales order page:

So, how is this achieved? The answer is in the black magic that is Regular Expressions, or regex. And it looks a little like this:

\w+ \d+ "*

Regex can be quite intimidating the untrained eye. I won’t try and explain it all, as folk much better than I have already done so. Effectively, regex is a method which allows us to define a pattern and return the results of that pattern. It’s uses are numerous, and once you get a grasp of the concept, it’s uses are endless.
For reference I include a link to the Wikipedia entry , a basic guide on how to use regular expressions, and most importantly my #1 favourite tool for learning/trying out my regex.

For our purposes today, there are only a few, simple terms required.
Firstly, in the search box of VS Code make sure you’ve selected the ‘Use Regular Expressions’ option

There are then three key components to this search:

• \w+ (Search for any word)
• \d+ (Search for any number)
• “* (Search regardless of whether there is a double quotation mark)

Objects in business central all* start out with three pieces of information:

• The object type
• The object ID
• The object name – which if including a space or special characters is surrounded by double quotation marks

I’m sure most of you at this point can guess where this is going.
The name of an object is a pattern, and we’ve got a regex which matches that pattern. Effectively we’re asking for: AnyWord_Space_AnyNumber_Space_MaybeADoubleQuote_TheObjectName

The catch all search is:

\w+ \d+ "*

If we wanted to search just within a specific set of object types, we can replace \w+ with the object type. eg:

codeunit \d+ "*

• \w is the regex term to match a letter
• \d is the term to match a number
• + is the term to match multiple of the preceding pattern
• * is the term to mean ‘0 or more’

Therefore \w+ says match any number of alphabetical characters, \d+ says to match any number of digits, and “* says to match 0 or more double quotation marks.
The space characters between the terms are part of the pattern – there must be a space between the word and the number, and there must be a space between the number and the maybe quotation mark.

The method isn’t perfect, and maybe better options exist.
For example, I suspect it could be expanded to use regex groups to match the term within an object name (such as the search for item also matching codeunit 1327 “Adjust Item Inventory”. However, I’ve not found enough need to spend time on working on it. If you do find ways to improve this, then please do let me know!

However, I find that for me personally this has made my navigation of the base app much easier.
And also, it’s made me that bit more familiar with regex – never a bad thing!

Whilst this post is primarily about the HTTPClient, I could not explain it without also delving into it’s brethren datatypes, namely HTTPHeaders, HTTPContent, HTTPResponseMessage and HTTPRequestMessage. I’ll firstly explain what each of these data types are for, and how they combine to form a whole HTTP request, then follow up with an example of how I utilise them in one handy wrapper function.

Firstly, is the HTTPClient itself. This is the main engine of our integration and handles the actual communication with the API or webservice. In fairly loose terms, it allows for us to initiate a Read (Get), Insert (Post), Modify (Put/Patch) or Delete (Delete) request to the webservice/API we wish to interact with.

For all of these requests, we need to provide the URL we are making the request to, and it is expected that all of these methods will provide some sort of response, and that is where the HTTPResponseMessage comes into play. By giving the call a HTTPResponseMessage variable, we will then be able to read & interact with that variable to understand the data that is passed back. This would primarily be in the form of the response content (JSON in my case, but other formats may be passed) or a HTTP Status code. 

ResponseMessage.Content().ReadAs(ResponseText);

If we need to pass some data as part of the request, then we would use a Post, Put or Patch request – all of these methods require that we pass some data and this is where the HTTPContent data type comes into play.
In short, the HTTPContent is the body of the request you’re trying to send. For the most part I simply load this from a text variable containing the message I want to send.

RequestContent.WriteFrom(payload);

You’ll also almost certainly need to provide some sort of authentication as part of your request. This is handled within the HTTPHeaders datatype. For my scenario basic authentication is fine, so that is what we’ll discuss here.
For this I’ll inherit my headers from the client, and then add a key/value pair into the headers

RequestHeaders := Client.DefaultRequestHeaders();
RequestHeaders.Add('Authorization',CreateBasicAuthHeader(Username,Password));

The value for this authentication header is created by a function which converts the username & password to a base64 string

procedure CreateBasicAuthHeader(UserName:Text;Password:Text):Text    var
TempBlob: Record TempBlob;
begin
TempBlob.WriteAsText(StrSubstNo('%1:%2', UserName, Password), TextEncoding::UTF8);
exit(StrSubstNo('Basic %1', TempBlob.ToBase64String()));
end;

However, I’ve found these to be somewhat limited in their use when it comes to the POST and PUT methods.

For these, I needed to be able to send more information than just the content and request headers, this is where the HTTPRequestMessage and the ‘SEND’ method is used.
This allows me to specify the content type I’m sending, as well as utilise other HTTP methods such as a ‘Patch’ rather than ‘Put’, which is required by some API/Webservices.

To specify the content type, I’ll utilise another HTTPHeader variable, but this time inherit from the HTTPContent, and then add the header key & value specifying my content type:

RequestContent.GetHeaders(contentHeaders);
contentHeaders.Clear();
contentHeaders.Add('Content-Type', 'application/json');

This can then be used with the POST/PUT methods as content directly.

If I require to use a different request message, I’ll instead add that content to my Request Message, and set the ‘Method’ of the request message to be the one the API requires, as well as loading the request URL :

RequestMessage.Content := RequestContent;
RequestMessage.SetRequestUri(RequestURL);
RequestMessage.Method := 'PATCH';

Now that’s all been put together, I can simply send the request

client.Send(RequestMessage, ResponseMessage);

To avoid repeating the code throughought my integration, and to give me a one stop method for my HTTPclient interactions, I’ve formed this up into a wrapper function:

procedure CallService(ProjectName: Text; RequestUrl: Text; RequestType: Enum HTTPRequestTypeEnum_ADO; payload: Text; Username: Text; Password: Text): Text
var
Client: HttpClient;
RequestHeaders: HttpHeaders;
RequestContent: HttpContent;
ResponseMessage: HttpResponseMessage;
RequestMessage: HttpRequestMessage;
ResponseText: Text;
contentHeaders: HttpHeaders;
begin
RequestHeaders := Client.DefaultRequestHeaders();
RequestHeaders.Add('Authorization', CreateBasicAuthHeader(Username, Password));

case RequestType of
RequestType::Get:
Client.Get(RequestURL, ResponseMessage);
RequestType::patch:
begin
RequestContent.WriteFrom(payload);

RequestContent.GetHeaders(contentHeaders);
contentHeaders.Clear();
contentHeaders.Add('Content-Type', 'application/json-patch+json');

RequestMessage.Content := RequestContent;

RequestMessage.SetRequestUri(RequestURL);
RequestMessage.Method := 'PATCH';

client.Send(RequestMessage, ResponseMessage);
end;
RequestType::post:
begin
RequestContent.WriteFrom(payload);

RequestContent.GetHeaders(contentHeaders);
contentHeaders.Clear();
contentHeaders.Add('Content-Type', 'application/json');

Client.Post(RequestURL, RequestContent, ResponseMessage);
end;
RequestType::delete:
Client.Delete(RequestURL, ResponseMessage);
end;

ResponseMessage.Content().ReadAs(ResponseText);
exit(ResponseText);
end;

The ‘Request Type’ is an enum with the following values:

value(0; Get) { }
value(1; patch) { }
value(2; post) { }
value(3; delete) { }

The answer is surprisingly easy, all we must do is look to processes and methods already used by MS themselves, that many of us are already familiar with.
In short, we can replicate the same process used for upgrades, migrate the data to upgrade tables, then process it into our extension tables, performing any transformation required along the way.

With a shift of perspective and an examination of the problem, the solution starts to seem a lot simpler.
We simply need to move data from one table to another.

The first, and most definite, complication is that the two objects we need to transfer between live in separate development environments.
This is solved by ensuring our symbols are generated for the table we’re moving from. Once this is done, and the symbols downloaded to our AL project (see here) and then refer to our C/AL table in our extension and run a basic data transfer process.

The second complication is that the two objects may have the same object IDs, so cannot exist in the tenant together at the same time. Again, there is a simple solution for this: we move our data to a temporary object range. The table sync that occurs when a table is compiled or removed already gives us a mechanism for this (see here). We simply create an upgrade table to hold our data, create an upgrade CU to handle the transfer of data to the upgrade table, then simply delete the original C/AL objects, let the table sync run, and then refer to the upgrade tables from your extension (don’t forget to update those symbols to include the upgrade table!)

I do have one small problem with doing the migration in my primary extension however.
As a conscientious developer it’s quite likely that I’ve done my best to develop this extension in a crisp, clean, cronus environment. In order to perform the data migration within this extension I must now add AL objects and symbols for C/AL objects which I only need temporarily – I would then need to remove and up-version my extension once I’m complete, in order to leave it clean and referencing the proper C/AL symbols, and to not be wasting some of that precious licence range.
This would be even more untenable if I were developing a product for consumption by other partners.

Therefore, I recommend handling the migration using a secondary, temporary extension which can be removed after, without affecting my primary extension.

Creating the secondary extension with a dependency on the first will allow for this secondary extension to utilise our new AL table from the primary extension, and we then only need to load our modified upgrade object symbols to the secondary extension.
We can then process the data from C/AL upgrade table to our AL table
within this migration extension; this could be via an install codeunit or through some other process you choose to run manually such as a processing report.

Once this is done, you can remove your upgrade table, remove your migration extension and you have a shiny, new extension with all of your old data, ready to rock.

I do not think it’s unreasonable to expect a standard replication tool to work right out of the box, but this one does not.

Why? 
Because the extensions that come as standard in SaaS are not the same as the extensions that come as standard on-prem, and so immediately you have different schemas. 
You simply cannot install BC on-prem, create a SaaS tenant and start replicating. 

At a very minimum you must uninstall standard extensions from the SaaS system before starting. That is bonkers.

Of course it makes a world of sense that you cannot have C/AL modifications in the database. Putting custom fields into existing tables and asking it to work is too much to ask. Anyone could have added anything, it’s a real nightmare However, if an extension that MS provides extends the G/L Setup, and I don’t have that in my on-prem environment, because I simply cannot put it there, why does any replicated data become totally inaccessible?

The reality of my first attempt to do this, is that I (and I admit this was a mistake on my part) upgraded my customer to BC on-prem, got that all set up and working with everything installed as per the upgrade documentation, and then thought ‘great, I’ll now get that replicating to SaaS ready for them to make the jump’. I then changed my company to look at data in one of the replicated companies and was unable to log in without a support call, as the g/l setup table had failed to replicate. And Business Central needs that setup table to function.

To make matters worse, once I’d removed the troublesome extensions, the problem did not go away. The ‘intelligent’ cloud seems unable to recognise when an extension has been removed. So even after realising my error, I was still left with no way to fix it. Not even using the ‘Reset Cloud Data’ option, or going through the setup process again resolved this. Again it took a support call to MS, which had to be referred to the dev team, to fix. 

And my final big issue with this tight coupling, is one that I feel is the biggest real world issue. My SaaS tenant, overnight, unknown to me until after the fact, got the upgrade to the latest build of BC SaaS. My replication now does not work. It will not work until I’ve gone to my customers account manager, asked them to communicate the bad news & arranged for our upgrade team to do a code roll up, our platform team to a platform roll up, and for our customer to test, sign off & accept the down time of their system during that roll-up.

Yes, of course, they’re on BC, they have no mods, it should be a doddle, and I’m sure it will be. Just replace a bunch of files. 
But rolling a customer up to a different CU is not as simple as just copying files.
It needs planning. Downtime is required. Different teams must be involved, processes planned & scheduled. Someone must pick up the cost. There is a risk.

Of course, this should all be largely automated, as it is for the SaaS environment. But anyone out there who supports live customers knows that getting to that point of automating upgrades & having the infrastructure to do so is a big ask when you’re also trying to juggle maintaining your existing customer base (of whom very little are on a version which has only been released for just under 2 months), and making sure that the chargeable work modifying & supporting existing systems keeps coming through the business to keep the lights on.
I’m very fortunate, I work for a company that is very keen on technological progression and indeed my day job is now to focus on making sure these processes are in place and that we can get things swifter & more automated. But how many partners can say that? How many people can invest time in automating this roll up? So instead, it becomes a tool that is difficult and costly to use. Even though in theory replicating data to the cloud is  as easy as pressing that ‘Assisted setup’ button and following some very clear, well documented steps.

This needs to be less closely coupled. It needs to allow for extensions not being identical, especially when they’re just standard extensions. It needs to allow for new builds getting put out there overnight. 
Of course there has to be limits. But roll ups & out of the box extensions are not that limit.

1) Intelligent Cloud disappears from ‘Tell Me’

This has happened for at least a week, and then returned with no clear explanation. In the meantime, you’re stuck wanting to see the status of your replication, or trigger a manual replication.

You can do so by adding ?page=4003 to the end of your URL. e.g.

https://businesscentral.dynamics.com/{TenantID}?page=4003

2) The tenant becomes completely inaccessible 

This one caused me the most trouble. In short, if any of the more important tables in your tenant fail replication, such as the G/L entry, then you may lose the ability to log in, getting a message like:

Could not open the ” company. Data from table General Ledger Setup is unavailable.Intelligent Cloud replication for this table was unsuccessful

The obvious answer, is to not have replication errors. Have your schema correct for all tables and this won’t happen. The reality is not that easy though

The realistic answer is to plan ahead for in case this happens. Have a company in your SaaS tenant which exists before you setup the replication, and does not match the company names that you will replicate. This company will then always be there, clean & unbroken. If you end up locked out, you can add ?Company=My%20Company where your company name is ‘My Company’. Of course, if your company name is not ‘My Company’ then you’ll need to add your company name instead. e.g.:

https://businesscentral.dynamics.com/{TenantID}?Company=My%20Company

3) Failure preparing data for table. Error message: Change tracking is not enabled on table

This came up as it was not documented that change tracking must be enabled; I covered this in my previous post, but include it again here for the sake of completeness.
So that the replication does not pass all data to the cloud every night, Microsoft make use of the ‘Change Tracking’ functionality in SQL to know which records have changed since the last replication run, and only replicate these. If change tracking is not enabled, you’ll get an error similar to the title of this section. 

If that occurs, you’ll need to run this SQL script to enable change tracking on the tables in your database (or do so however you see fit, so long as it ends up enabled for the tables erroring!)

4) Failed Table does not exist in local instance.

The replication works by asking ADF to pull data for specific tables. If for any reason the table does not exist in your on-prem system, this is the error you’ll get. I got it for the test tool tables, as these were not present. Your only option is to make sure those tables exist and run again. I have had situations where those tables were removed from the SaaS instance, by removing extensions, but the issue persisted. This had to be resolved via a support call, but should no longer occur in future builds. 

5) The schema of the on-premises table does not match the corresponding Business Central cloud table.

This is very similar to the above – the tables do not match. The only option here is to resolve that, again, as above. I got this due to the SaaS system being upgraded to the latest build. The only option there is to upgrade the on-prem environment to the matching CU. 
I suspect this will be quite common, as you will likely not be expecting the SaaS upgrade.

When it comes to migrating or upgrading these changes, you may decide you only want to start reviewing or processing those objects which have been modified. For my part, I’m in the process of converting a modification from 2017 to an extension ready to go on BC. Fortunately, this was always planned to be a stand-alone product, so was developed & kept in it’s own branch in our TFVC repo. 

However, as per our standard process, this repo includes all nav objects for the database it was developed upon. 
I now wanted to load those objects into a clean, shiny database (created in a docker container, using the standard MS images, of course) and rather than load all of those objects & suffer the tedium that follows, I wrote a script to identify objects within the branch which have been modified, and then I only need to load those objects into my base application.

Now, this is not the neatest or most efficient way to do this, and I’m certainly not the powersell guru that @waldo1001 is, but it works nicely with the setup I already have, and gives me the option to either run this for a single file containing all text objects, or a folder with one object per file. 

In short, you provide a file path, the system identifies if this is a file or a directory, and then creates a variable filled with all the text files. 
It then creates a nice clean target folder, runs through the objects & identifies if they have a ‘Time’ element that is equal to ’12:00:00′ or does not have a ‘Modified’ property tag. If both of those conditions are not met, then the file will be moved to the copy directory. 

I expect to find quite a lot of use for this as we transition from C/Al to extension, and hopefully it will be of some help to you too!

Once you’ve taken the time to make sure that you’ve migrated your customer to a standard Business Central on-premise instance, the full glory of replicating data from that instance to a cloud instance is just a few clicks away.

It’s also, surprisingly, documented very clearly, but like most BC documentation it can be hard to find via google (I’ve looked up the page 6 or 7 times now, and I still never find it on my first search term).

So what do we need to know?

Replication is achieved by utilising the ‘Intelligent Cloud’ which comes included with your Business Central SaaS tenant – even in a trial. In short, you connect an existing SQL database to Azure using a tool provided by Microsoft, and with a little configuration this will suck the data right out of your on-prem database & shoot it up into your cloud, leaving you with two systems that match exactly.

This has a few caveats though. It means that the two database schemas must match exactly. The exact same extensions must be on the cloud & on-prem, there must be absolutely no modifications in C/AL, and you must have installed the test tool on your on-prem database (but I’m sure you’ve done that anyway, who wouldn’t want the test tool?!).

Also, in the interest of full disclosure, I’ve had 2 weeks of support calls with MS between starting on this & having it working. I’ll detail this more in a later post, but I’m confident that it is possible to do this yourself, if the proper work is done up front. The bigger issues I’ve faced were bugs in the process and have now been resolved by the development team at MS.

It all starts, by migrating to Business Central on-premise. I’ll not go into detail about that in this already lengthy post (look for future updates!) but this is very similar to the NAV upgrade process we’ve been following for years. Convert the database, migrate the data, you’re on BC. 

Once that’s completed, you’ll need to make sure the on-prem database has a compatibility level of 130, and (this is undocumented) enable change tracking on your SQL database tables. I’ve included a SQL script below that will do this. When data is replicated from your on-prem tenant to the cloud, it will only replicate data which has changed since the previous replication run; change tracking allows the system to know which data has changed & selectively replicate it.

You’ll then need to review which extensions are installed on-prem and in the SaaS environment. Of course, having followed the upgrade steps to the letter, you’ll have installed the extensions included in the BC install media, which includes the intelligent cloud stuff. There are several standard extensions which only exist for SaaS however, and you’ll need to remove those, as well as making sure any custom extensions which you’ve added to the on-prem tenant are also installed up in the cloud.

I cannot stress enough the importance of having the exact same extensions in both systems, as well as having absolutely no C/AL modifications. I’d also recommend making sure you have the same localisation for each version.

With that complete, you’re now prepared & ready to start the migration process in earnest. 
Simply go to ‘Assisted Setup’ in your cloud environment and then select ‘Set up Intelligent Cloud’

You’ll then be presented with a wizard. Agree to the legal stuff, and then on the next page use the lookup to select ‘Dynamics 365 Business Central’, then leave ‘SQL Configuration’ as SQL Server, give it a SQL connection string & if this is your first time setting up the intelligent cloud, also leave the ‘Integration Runtime Name’ blank.
If you click the ‘SQL Connection String’ label, you’ll get a handy tool tip with an example you can copy:

The UserID & Password need to be for a user account which uses SQL authentication, which has both read & modify permissions on your on-prem database. There are some stored procedures created in order to run this. We went with an account set as DBO, but I’m not a SQL admin so would advise you consider the security level you wish to give to this account for yourself. 

Once you’ve pressed ‘Next’ you’ll be given some details of how to download & setup the ‘Self Hosted Integration Runtime’.
This is a tool which allows for the communication of data between Azure Data Factory & a on-premise SQL database. 
It must be installed on a server which can connect to the SQL server; The SHIR can be reused for multiple connections, for different databases, and for purposes which are not BC related, so I’d recommend installing it somewhere central if you have multiple customers utilising the same SQL server, or multiple SQL servers on the same network.

After this, if your config is correct, you’ll get a list of companies to select from. If it’s not successful, you’ll get an error. You can diagnose this by going to the server where the SHIR is installed, and looking at the event viewer, under ‘Applications and Services Logs’ > ‘Connectors – Integration Runtime’

If things have gone wrong, there will likely be errors and warnings in there. 

If things have gone successfully, you’ll be asked to setup a schedule. Do bare in mind that this can lock tables, so I’d suggest making it run at a quiet time.

Once the wizard is complete, you’ll find that your SaaS tenant now includes all the companies you selected to replicate (with no data in them yet), but that the SaaS environment has become effectively ‘read only’, with all user permissions dropped.
This is because the replication is one way. Once you’ve got all the data you want and you’re ready to move to SaaS as the main system, you simply disable the cloud replication, set your user permissions & enjoy the world of cloud.
The data will be migrated whenever you’ve scheduled it for, in my experience this took around an hour from the scheduled time to completion.

I’ll follow up with another post which details some of the issues I’ve faced after setup & how to manage your replication, as well as how to investigate & resolve issues I’ve faced. 

The SQL Script to enable the change tracking is below:

DECLARE @ReplicatedTables AS TABLE (Id int, [Table Name] nvarchar(128))
INSERT INTO @ReplicatedTables
SELECT ROW_NUMBER() OVER (ORDER BY [Company Name], [Table Name]), [Table Name] FROM [Intelligent Cloud Status]

DECLARE @i int = 0, @modifiedCount int = 0
DECLARE @count int = (SELECT COUNT(*) FROM @ReplicatedTables)
WHILE @i < @count
BEGIN
    SET @i += 1
    DECLARE @TableName nvarchar(128)
    SELECT @TableName = [Table Name] FROM @ReplicatedTables WHERE Id = @i
    IF NOT EXISTS(SELECT TOP 1 1 FROM sys.change_tracking_tables WHERE object_id = OBJECT_ID(@TableName))
    BEGIN
        DECLARE @sql nvarchar(250)
        SET @sql = 'ALTER TABLE ' + QUOTENAME(@TableName) + ' ENABLE CHANGE_TRACKING'
        EXEC sp_executesql @sql
        SET @modifiedCount += 1
    END
END

SELECT 'Enabled change tracking on ' + CAST(@modifiedCount as nvarchar(12)) + ' tables.'