Pinning GAS Servers
Using Global Access Server (GAS) pinning, you can manage large deployments of multiple servers across multiple regions or countries. You can configure GAS pinning using RAE services and Thing properties to define a custom list of countries or regions, and then pin remote Things to specific GAS servers. This enables you to comply with local data transfer laws and regulations by keeping data in a specific country or region.
You can enable GAS pinning for a remote Thing by setting the isPinningEnabled property to true on a remote Thing. You can pin remote Things to GAS servers in one of three ways: by country, by region, or manually by specifying the server for a remote Thing using the pinnedGASList infotable property. By default, the GAS server selection is controlled using a service that checks the available capacity of the server and selects the one with the most available capacity. When pinning is enabled, remote sessions are only established with the pinned GAS server.
The following table lists properties that enable you to configure GAS pinning for each remote Thing in ThingWorx:
|
Property
|
Description
|
Base Type
|
Default Value
|
|---|---|---|---|
|
isPinningEnabled
|
Controls whether GAS pinning is enabled.
|
BOOLEAN
|
False
|
|
pinnedCountries
|
An infotable that specifies the countries that the agent connects to.
|
INFOTABLE
|
N/A
|
|
pinnedGASList
|
Infotable that contains the pinned GAS names. Use for manual pinning.
|
INFOTABLE
|
N/A
|
|
pinnedRegions
|
An infotable that specifies the regions that the agent connects to.
|
INFOTABLE
|
N/A
|
|
pinningType
|
A THINGNAME property. The value can be a name of thing which implements GASPinningType Thing Shape. Options:
• CountryPinning
• RegionPinning
• ManualPinning
|
THINGNAME
|
CountryPinning
|
• PinCountry—Pins the remote Thing to a country by adding a country value to the pinnedCountries property.
• UnpinCountry—Unpins the remote Thing from a country by removing the country value from the pinnedCountries property.
• PinRegion—Pins the remote Thing to a region by adding a region value to the pinnedRegions property.
• UnpinRegion—Unpins the remote Thing from a region by removing the region value from the pinnedRegions property.
• PinGASThing—Pins the remote Thing to a specific GAS by adding a GAS Thing name value to the pinnedGASList property.
• PinGASFromCountry—Pins all GASModel Things with a country value equal to the input by adding their thingName to the pinnedGASList property.
• PinGASFromRegion—Pins all GASModel Things with a region value equal to the input by adding their thingName to the pinnedGASList property.
For more information about the properties and services that available for a remote Thing, see GASRemoteAccessible Thing Shape.
For more information about the properties and services that are available for a GAS Thing, see GASLocation Thing Shape.
Pinning Remote Things to a GAS Server by Country
To use configure country pinning in the ThingWorx platform, perform the following steps:
1. Define a list of country names within the GASCountriesTable data table Thing. This table includes a list of countries that you can use to pin GAS servers.
a. In Composer, open the GASCountriesTable data table Thing.
b. On the Services tab, use a service such as AddDataTableEntry.
c. Click to execute the service.
d. In the Execute Service dialog, define the values that you want to add data table.
e. Under values, click the values infotable.
f. In the values dialog, click Add, then type the country name in the input box.
g. Click Add, then Save.
 | You can use other services such as AddDataTableEntries to add multiple country values at the same time. |
2. Pin GAS Things to a specific country that you added in the previous step.
a. In Composer, open a GAS Thing that implements the GASModel Thing Shape.
b. On the Services tab, execute the UpdateCountry service.
c. Under Inputs, type a country value, then click Execute.
d. The country property of the GAS Thing is updated.
| | The input is validated based on the values that are stored in the GASCountriesTable data table Thing. |
e. Click Save.
3. Configure a remote agent Thing to use country pinning:
a. In Composer, open a remote Thing that implements the GASRemoteAccessible Thing Shape, then open the Properties and Alerts tab.
b. Set the isPinningEnabled property value to True.
c. Set the pinningType property value to CountryPinning.
4. Specify the countries to pin the remote Thing to using the PinCountry service:
a. On the Services tab of the remote Thing, click Execute next to the PinCountry service. The Execute Service dialog box opens.
b. Type a country name under country, then click Execute.
| | Country names are case not case sensitive. |
The service validates input with stored country names in the GASCountriesTable and then updates the pinnedCountries property with name of the country. To remove a county from the property, use the UnpinCounty service.
5. Click Save to save the changes to the remote Thing.
When GASSelector.SelectServer is executed, the CountryPinning.GetPinningFilter service is executed, which returns a ThingWorx Query filter with a list of countries from the pinnedCountries property. A GAS server is selected with a matching value from the list of countries in the pinnedCountries property.
Pinning Remote Things to a GAS Server by Region
To use configure region pinning in the ThingWorx platform, perform the following steps:
1. Define a list of region names within the GASRegionsTable data table Thing. This table includes a list of regions that you can use to pin GAS servers.
a. In Composer, open the GASRegionsTable data table Thing.
b. On the Services tab, use a service such as AddDataTableEntry to add entries to the data table.
c. Click to execute the service.
d. In the Execute Service dialog, define the values that you want to add data table.
e. Under values, click the values infotable.
f. In the values dialog, click Add, then type the region name in the input box.
g. Click Add, then Save.
| | You can use other services such as AddDataTableEntries to add multiple region values at the same time. |
2. Pin a GAS Things to a specific region that you defined in the previous step.
a. In Composer, open a GAS Thing that implements the GASModel Thing Shape.
b. On the Services tab, execute the UpdateRegion service.
c. Under Inputs, type a country value, then click Execute.
d. The region property of the GAS Thing is updated.
| | The input is validated based on the values that are stored in the GASRegionsTable data table Thing. |
e. Click Save.
3. Configure a remote Thing to use region pinning.
a. In Composer, open a remote Thing that implements the GASRemoteAccessible Thing Shape, then open the Properties and Alerts tab.
b. Set the isPinningEnabled property value to True.
c. Set the pinningType property value to RegionPinning.
4. Specify the regions to pin the remote Thing to using the PinRegion service:
a. On the Services tab of the remote Thing, click Execute next to the PinRegion service. The Execute Service dialog box opens.
b. Type a region name under region, then click Execute.
| | Region names are not case sensitive. |
The service validates input with stored region names in the GASRegiounsTable and then updates the pinnedRegions property with name of the region. To remove a region from the property, use the UnpinRegion service.
5. Click Save to save the changes to the remote Thing.
When GASSelector.SelectServer is executed, the RegionPinning.GetPinningFilter service is executed, which returns a ThingWorx Query filter with a list of regions from the pinnedRegions property. A GAS server is selected with a matching value from the list of countries in the pinnedRegions property.
Pinning Remote Things to a GAS Server Manually
You can manually pin specific remote Things to a GAS remote Thing. To use manual pinning, perform the following steps:
1. Configure a remote agent Thing to use manual pinning:
a. In Composer, open a remote Thing that implements the GASRemoteAccessible Thing Shape, then open the Properties and Alerts tab.
b. Set the isPinningEnabled property value to True.
c. Set the pinningType property value to ManualPinning.
2. Use the pinnedGASList property to specify one or more GAS servers that can be used when making connections to the remote Thing.
◦ Edit the pinnedGASList property value.
◦ To add a new value, click Add , then select a GAS server Thing entity.
◦ Click Add, then Save to save the value.
You can use the FetchAndAddGASFromCountryToList and FetchAndAddGASFromRegionToList services to automatically add all GAS servers that are associated with a country or a region to the pinnedGASList property.
3. Click Save to save the changes to the remote Thing entity.
When GASSelector.SelectServer service is executed, the ManualPinning.GetPinningFilter service returns a ThingWorx Query filter with a list of available GAS servers within the pinnedGASList property. A GAS server is selected from the list.