Shop configuration global.config - WEBSALE Dokumentation

The global.config is a shop’s cross-subshop configuration file. Whatever is set here applies to all subshops together. A different setting at subshop level is not intended; that is what the shop configuration shop.config is for. In a newly delivered shop, this file does not exist. It is only created when a function needs it, and it then contains only the sections of those functions. There is no standard version that would have to be filled out completely. Reference: Shop configuration shop.config

Creating the file

The global.config is located in the online service area in the “Configuration” service directly under “Global”. To create it, click the “create new configuration” icon to the right of the word “Configurations” and name the new configuration global. The system adds the file extension itself.

You then have an empty configuration file into which you enter the sections you need.

Who reads the file

The global.config is not only evaluated by the shop system itself. Depending on the section, a different program reads it, which explains why some changes take effect immediately and others only with the next run of a background program.

Section	Purpose	Read by
`ChargeLabel`	Make the label of the voucher batch a mandatory field	Voucher management
`ChargeLabelValues`	Selection list of batch labels	Voucher management
`Common`	Individual basic settings of the shop	Shop system
`Conversions`	Encoding of the additional inputs in the order data	Shop system
`CustomerImportPro`	Customer import	Import program
`FuturaECS`	Stock retrieval from Futura	Import program
`ImportCharsetConvertMap`	Character set conversion during import	Import programs
`ProductDataFieldInjection`	Set product data fields for test scenarios	Shop system
`ProductImportPro`	Product import	Import program
`SpecialUserCodes`	Fill suffix fields of the billing address via a code	Shop system
`SpecialW2PConditions`	Conditions for conditionally web-to-print-capable products	Shop system
`SubShopMapping`	Combine subshops into groups	Shop system and import programs
`TopSeller`	Top seller sorting and top 30 products	Analysis program
`VoucherNumberCharacters`	Exclude characters from the voucher number	Voucher management

The shop system reads the global.config as needed within a page request. Changes to the sections that the shop system evaluates therefore take effect immediately. The sections for imports, analyses and voucher management are only read on the next run of the respective program or the next time the respective page is opened in the service area.

Common

This section collects individual basic settings that do not belong to a section of their own.

<Common>
   ProductData-ResetOnEmptySetDefinition       =
   ProductData-ResetOrgPriceWhenOrgPricesIsEmpty =
   FORMTagsResetInputCounter                   =
   OrderFile-WriteCCDataOnApplePay             =
   OrderFile-WriteCCDataOnGooglePay            =
   MaxRedeemableVouchers                       =
</Common>

Parameter	Description	Values
`ProductData-ResetOnEmptySetDefinition`	If an import delivers an empty set definition for a dependent variant, the existing definition as a set product is reset. Without this parameter, the old definition remains.	`yes`, `no`. Default `no`
`ProductData-ResetOrgPriceWhenOrgPricesIsEmpty`	The same mechanism for the strike-through price. If the import no longer delivers a strike-through price, the existing one is deleted instead of kept.	`yes`, `no`. Default `no`
`FORMTagsResetInputCounter`	Resets the internal counter for form field names to 1 with every new `form` element. Without this parameter, the shop system counts continuously across all forms on a page.	`yes`, `test`, `no`. Default `no`
`OrderFile-WriteCCDataOnApplePay`	Controls whether the credit card data is written to the order data for a payment via Apple Pay.	`yes`, `no`. Default `yes`
`OrderFile-WriteCCDataOnGooglePay`	The same for Google Pay.	`yes`, `no`. Default `yes`
`MaxRedeemableVouchers`	Maximum number of vouchers that can be redeemed at the same time, including the first one. Values outside the valid range are set to the nearest limit.	Integer 1 to 10. Default 10

In the legacy documentation, the description of a different parameter appears under ProductData-ResetOnEmptySetDefinition. It explains the input counter for form fields, and the values yes, test and no listed there also belong to that other parameter. What is meant is FORMTagsResetInputCounter. Both parameters are described separately above. ProductData-ResetOnEmptySetDefinition only knows yes and no and has nothing to do with forms.

FORMTagsResetInputCounter is mainly useful on pages that preload product data dynamically, for example via CAT-AdvData or CAT-LoadData. If there are several product forms on one page, the sequentially assigned field names can overlap and inputs can be assigned to the wrong form. With test, you first activate the change only in the shop’s test mode and check the effect before switching to yes.

Conversions

Determines whether the additional inputs for products are passed hex-encoded into the order data. This is necessary if the inputs can contain characters that interfere with the format of the order data, for example line breaks.

<Conversions>
   OrderFile-ProductExtraInput   =
   OrderFile-ProductExtraInput1  =
   OrderFile-ProductExtraInput2  =
   ...
   OrderFile-ProductExtraInput20 =
</Conversions>

Parameter	Description	Values
`OrderFile-ProductExtraInput`	Default for all indexes that are not configured individually.	`none`, `hex`. Default `none`
`OrderFile-ProductExtraInput1` to `OrderFile-ProductExtraInput20`	Rule for the respective additional input field. A value set here takes precedence over the default.	`none`, `hex`. The default is the value of the default setting

There are exactly 20 additional input fields per product, which is why the series ends at 20. An individually set parameter always wins, even if it says none and the default is hex. Any value other than hex is read as none.

The encoded values appear in the order data in the ExtraInput_<Nummer> block of the respective item. The receiving merchandise management system must know the encoding and reverse it.

ProductDataFieldInjection

Sets product data fields for test scenarios without the data from the merchandise management system having to be changed. This lets you add, overwrite or clear product information at short notice.

<ProductDataFieldInjection>
   <+InjectData>
      Allow                 =
      ProductPattern-List   =
      AllowForSubShops-List =
      DenyForSubShops-List  =
      ForceOverwrite        =
      <+SetData>
         Fieldname =
         Value     =
      </+SetData>
   </+InjectData>
</ProductDataFieldInjection>

Guide: Enriching product data for test scenarios

Subsection +InjectData

Each +InjectData subsection describes a rule. You can create as many of them as you like.

Parameter	Description	Values
`Allow`	Determines whether and in which operating state the stored data is passed. `no` switches the rule off, `test` restricts it to the shop’s test mode, `yes` also applies in live operation.	`yes`, `no`, `test`. Default `yes`
`ProductPattern-List`	Determines which products the rule covers. Mandatory, see the table below.	Patterns, comma-separated
`AllowForSubShops-List`	Optional. Restricts the rule to the listed subshops.	Comma-separated list of subshop IDs
`DenyForSubShops-List`	Optional. Excludes the listed subshops from the rule. This setting takes precedence over `AllowForSubShops-List`.	Comma-separated list of subshop IDs
`ForceOverwrite`	Overwrites a value supplied by the merchandise management system. Without this parameter, the rule only affects empty fields.	`yes`, `no`. Default `no`

If ProductPattern-List is missing or the value is empty, the entire rule is skipped. This happens without an error message in the shop.

ForceOverwrite = yes affects runtime and performance unit consumption, because each covered product must additionally be checked and written. Only set the parameter where overwriting is really needed.

Subsection +SetData

Within +InjectData, you use any number of +SetData subsections to define which fields receive which value.

Parameter	Description	Values
`Fieldname`	Technical field name of the product data field	for example `IS-ZUSATZ49`
`Value`	Value written to this field	any text

Patterns for ProductPattern-List

Pattern	Covers
`PI:*`	all products
`PN:123*`	products whose product number starts with `123`, followed by any number of characters
`PN:123?`	products whose product number starts with `123`, followed by exactly one arbitrary character
`PI:12?4`	products whose product index is four characters long, starts with `12`, ends with `4` and has an arbitrary character in third position

PN: checks the product number, PI: the product index. As wildcards, * stands for any number of characters and ? for exactly one character.

The section is only evaluated if the function is enabled for the shop. If it is not, the shop system logs an error and skips the entire section. You can get it enabled through your WEBSALE contact.

SpecialUserCodes

Automatically fills suffix fields of the billing address when the customer enters a predefined code or arrives in the shop via a link with the matching parameter. This lets you assign customers to a customer group or a sales channel during registration, for example. The customer only enters a readable alias. Which technical value results from it is defined exclusively in this configuration and is neither visible to nor changeable by the customer.

<SpecialUserCodes>
   <+SuffixCode>
      ID           = kundengruppe
      SuffixNumber = 13
      <+Entry>
         +Input = XXL
         Value  = gold
      </+Entry>
      <+Entry>
         +Input = BASIS
         Value  = silver
      </+Entry>
   </+SuffixCode>
</SpecialUserCodes>

If the customer enters XXL, suffix field 13 of the billing address then contains the value gold.

Parameter	Description	Values
`+SuffixCode`	Subsection, defines an assignment rule. Several rules are possible.
`ID`	Technical ID of the rule. The HTML field name `ws_suc_input_<ID>` is derived from it.	Digits and lowercase letters. All other characters are removed
`SuffixNumber`	Number of the suffix field of the billing address that is filled on a match.	1 to 50
`+Entry`	Subsection, defines an assignment of input to value. Several entries per rule are possible.
`+Input`	Accepted input. Several `+Input` lines in one entry are aliases for the same value.	Text, maximum 1024 bytes. Multibyte characters are supported
`Value`	Technical value written to the suffix field on a match.	Text, maximum 64 characters

The comparison of the input is not case-sensitive. An entry with +Input = XXL therefore also matches the input xxl. A second +Input line for the same spelling in different capitalization is unnecessary. You only need several +Input lines for genuinely different aliases.

A suffix field that already contains a value is not overwritten. The input then results in an error. The same applies if the input does not match any entry.

The function only works for logged-in customers. On a match, the shop system writes the value to the billing address and saves it. If the address check or saving fails, all suffix values set in this request are reverted.

The SUC- tag family is available for the input field and the feedback in the template.

SpecialW2PConditions

Determines under which conditions a product marked as “conditionally web-to-print-capable” is actually web-to-print-capable. Suffix fields of the customer’s billing address are checked.

<SpecialW2PConditions>
   <+AddressFieldCondition>
      <+Condition>
         Field          =
         Type           =
         Value          =
         BasketBehavior =
      </+Condition>
   </+AddressFieldCondition>
</SpecialW2PConditions>

Parameter	Description	Values
`+AddressFieldCondition`	Subsection. Several of these subsections are combined with OR.
`+Condition`	Subsection. Several conditions within one `+AddressFieldCondition` are combined with AND.
`Field`	Name of the suffix field of the billing address to be checked	for example `Suffix15`
`Type`	Type of check, see the table below
`Value`	Optional. Comparison value or comma-separated list, depending on `Type`.
`BasketBehavior`	Determines whether one product or all products in the basket must meet the condition.	`match-all`, `match-once`. Default `match-all`

Values for Type

Value	Condition
`empty`	The field is empty
`filled`	The field is filled
`value`	The value of the field matches `Value`
`notvalue`	The value of the field does not match `Value`
`inlist`	The value of the field is in the list `Value`
`notinlist`	The value of the field is not in the list `Value`
`includedinlist`	The value from `Value` is in the field’s list of values
`notincludedinlist`	The value from `Value` is not in the field’s list of values
`matchsimplewildcard`	The value of the field matches `Value` including wildcards. `?` stands for exactly one character at any position, `*` for any characters and may only appear at the end
`notmatchsimplewildcard`	The value of the field does not match `Value` including wildcards

The following example makes a conditionally web-to-print-capable product available as soon as one of the two fields Suffix15 or Suffix16 of the billing address is filled.

<SpecialW2PConditions>
   <+AddressFieldCondition>
      <+Condition>
         Field = Suffix15
         Type  = filled
      </+Condition>
   </+AddressFieldCondition>

   <+AddressFieldCondition>
      <+Condition>
         Field = Suffix16
         Type  = filled
      </+Condition>
   </+AddressFieldCondition>
</SpecialW2PConditions>

Guide: Web-to-print products

The conditions are read from the configuration on every page request, regardless of whether there is a conditionally web-to-print-capable product in the basket at all. Keep the section short for this reason. Coordinate the setup with your WEBSALE contact.

SubShopMapping

Combines subshops into groups and determines how products and categories are mapped to each other between the subshops of a group. The automatic generation of the hreflang attributes, for example, builds on this.

<SubShopMapping>
   <+SubShopGroup>
      Name                   =
      ID                     =
      ProductAllocation      =
      ProductAllocationFile  =
      CategoryAllocation     =
      CategoryAllocationFile =
      +SubShopID             =
      +SubShopID             =
   </+SubShopGroup>
</SubShopMapping>

Parameter	Description	Values
`+SubShopGroup`	Subsection, defines a group of subshops
`Name`	Optional. Freely assigned name of the group.	Text, for example `Shopgruppe_Endkunden_Produktivshops`
`ID`	Unique ID of the subshop group	alphanumeric
`ProductAllocation`	Type of product mapping. `sameIndex` maps via the product index, `mappingImport` via a mapping list, `no` switches the mapping off.	`sameIndex`, `mappingImport`, `no`. Default `no`
`ProductAllocationFile`	Path to the mapping list in the FTP access area. Only needed with `ProductAllocation = mappingImport`.	Path to a .csv or .json file
`CategoryAllocation`	The same for categories.	`sameIndex`, `mappingImport`, `no`. Default `no`
`CategoryAllocationFile`	Path to the mapping list for categories. Only needed with `CategoryAllocation = mappingImport`.	Path to a .csv or .json file
`+SubShopID`	ID of a subshop in the group. One line per subshop, at least two.	for example `DE-deutsch`

Coordinate the paths to the mapping lists with WEBSALE technical staff so that the files are in the expected location and are read at the right time.

Guide: Automatic generation of the hreflang attribute

TopSeller

Controls two functions that share the section but are independent of each other: sorting by top sellers and the “Top 30 products” function.

<TopSeller>
   NumDays      =
   Allow        =
   MaxAge       =
   ProductCount =
</TopSeller>

Parameter	Description	Values
`NumDays`	Sales period in days used to determine the top sellers. Belongs to sorting by top sellers.	Integer
`Allow`	Switches the “Top 30 products” function on or off.	`yes`, `no`. Default `no`
`MaxAge`	Maximum age of an order in days for it to be considered for “Top 30 products”.	Integer up to 1460, which corresponds to four years. Default 1460
`ProductCount`	Maximum number of products stored and output per customer.	Integer up to 100. Default 30

Allow refers exclusively to “Top 30 products”. Sorting by top sellers is not affected and is controlled solely via NumDays and the sorting in the template. So Allow = no does not switch off top seller sorting.

The analysis runs in a background program. A changed setting only takes effect the next time this program runs and rebuilds the table.

Guide: Sorting by top seller, Top 30 products

ChargeLabel

Determines whether a label must be specified when creating a voucher batch.

<ChargeLabel>
   Mandatory =
</ChargeLabel>

Parameter	Description	Values
`Mandatory`	The label for the voucher batch is a mandatory field.	`yes`, `no`. Default `no`

Guide: Creating and importing vouchers

ChargeLabelValues

Fills the selection list from which the label is chosen when creating a voucher or a voucher batch.

<ChargeLabelValues>
   +Value = Label1
   +Value = Label2
   +Value = Label3
</ChargeLabelValues>

Parameter	Description	Values
`+Value`	An entry in the selection list. One line per entry.	any text

Guide: Creating and importing vouchers

VoucherNumberCharacters

Excludes individual characters from the automatic generation of voucher numbers. This is useful for characters that are easily confused when typing, for example 1 and I.

<VoucherNumberCharacters>
   Exclude = 1,I,Z
</VoucherNumberCharacters>

Parameter	Description	Values
`Exclude`	Comma-separated list of the characters to exclude. Spaces around the entries are removed, lowercase letters are automatically converted to uppercase.	Digits `1` to `9` and uppercase letters `A` to `Z`. At most 10 characters

More than 10 excluded characters are not accepted. Voucher management shows an error message when generating and only uses the first 10 entries of the list.

The voucher generator only uses part of the alphabet anyway. The digit 0 and the letters O, W and X do not appear in generated voucher numbers. Excluding these characters therefore changes nothing. So the risk of confusing 0 and O does not exist for generated numbers at all.

The setting applies platform-wide to all shops and subshops. It only affects automatically generated numbers. A manually assigned voucher number is not restricted by it.

Sections for imports and third-party systems

These sections belong to interfaces and are not read by the shop system but by the respective import programs. The full description of the parameters is in the interface documentation.

CustomerImportPro

Concerns the customer import, in particular the conversion of character sets.

<CustomerImportPro>
   ...
</CustomerImportPro>

ProductImportPro

Concerns the product import, including the conversion of character sets.

<ProductImportPro>
   ConvertCharset     =
   ImportCharset      =
   UnknownCharacters  =
   CreateBestPrices   =
   MinCountCategories =
   MinCountProducts   =
</ProductImportPro>

ImportCharsetConvertMap

Defines the character set conversion table for the imports. The section can occur several times and is therefore written with a plus sign.

<+ImportCharsetConvertMap>
   ...
</+ImportCharsetConvertMap>

FuturaECS

Concerns exclusively the Futura merchandise management system.

<FuturaECS>
   SkipBranchIds =
</FuturaECS>

Parameter	Description	Values
`SkipBranchIds`	The listed branches are excluded from the stock calculation. Their stock is not included in the stock in the shop.	Comma-separated list of branch IDs, for example `1,2,5`

You can find the description of the remaining parameters of these sections in the interface documentation at https://doku.websale.de/schnittstellen.

Further sections

The shop system evaluates four further sections in the global.config that are not described in the previous documentation. They belong to functions that are enabled separately and set up together with WEBSALE.

Do not set up these sections without coordinating with your WEBSALE contact. Two of the four functions intervene in price calculation and in the payment process respectively, and they require activation, without which the section has no effect.

TaxCases

Defines country groups to which the tax case interface refers. The groups are formed in two subsections, once by delivery country and once by country of production.

<TaxCases>
   <DeliveryCountryGroups>
      <+Entry>
         ID          =
         CountryList =
      </+Entry>
   </DeliveryCountryGroups>

   <CountryOfProductionGroups>
      <+Entry>
         ID          =
         CountryList =
      </+Entry>
   </CountryOfProductionGroups>
</TaxCases>

Parameter	Description	Values
`+Entry`	Subsection, defines a country group
`ID`	ID of the group by which it is referenced	Text
`CountryList`	Countries of the group. Spaces are removed.	Comma-separated list of country codes

PaymentBruteForceProtection

Blocks payment methods after repeatedly failed payment attempts, separately per session and per IP address, and can additionally enforce a captcha.

<PaymentBruteForceProtection>
   ProtectedPayments-List                     =
   BlockTimesPerSession-List                  =
   BlockTimesPerIP-List                       =
   BlockTimesPerIP-ObservationWindowInMinutes =
   ForceCaptchaAfterXAttempts                 =
   UseCaptcha                                 =
   CaptchaErrorHandling                       =
</PaymentBruteForceProtection>

Parameter	Description	Values
`ProtectedPayments-List`	Payment methods to which the protection applies	Comma-separated list
`BlockTimesPerSession-List`	Block times per session, staggered by the number of failed attempts	List of pairs in the form `(Fehlversuche:Sekunden)`
`BlockTimesPerIP-List`	The same per IP address	List of pairs in the form `(Fehlversuche:Sekunden)`
`BlockTimesPerIP-ObservationWindowInMinutes`	Time window in minutes within which the failed attempts of an IP address are counted	Integer 1 to 2880, which corresponds to 48 hours
`ForceCaptchaAfterXAttempts`	From this number of failed attempts, a captcha is required	Integer
`UseCaptcha`	Captcha method used	`ReCaptchaV3`, `FriendlyCaptcha`, `CaptchaEU`
`CaptchaErrorHandling`	Behavior when the captcha check fails technically. `fail-open` lets the process through.	`fail-open`

An entry in the block time list consists of the number of failed attempts and the block duration in seconds, both in round brackets and separated by a colon. Several entries are strung together.

BlockTimesPerSession-List = (3:300)(5:3600)(10:permanent)

Entry	Meaning
`(3:300)`	block for 300 seconds from 3 failed attempts
`(10:permanent)`	block permanently from 10 failed attempts

The entry with the highest threshold reached always applies. A block duration of more than 48 hours is shortened to 48 hours. The value permanent only takes effect in the session list. An IP address is never blocked permanently, even if permanent is configured.

ProductDataJSONInterface

Describes from which file and which data field the customer-specific discount categories are read.

<ProductDataJSONInterface>
   <UserDiscountCategory>
      JSONFile  =
      DataField =
   </UserDiscountCategory>
</ProductDataJSONInterface>

Parameter	Description	Values
`JSONFile`	Naming scheme of the JSON file	Path with naming scheme
`DataField`	Name of the data field to evaluate	Text

CustomOfferAPI

Stores the secret for the interface for customer-specific offers.

<CustomOfferAPI>
   Secret =
</CustomOfferAPI>

Parameter	Description	Values
`Secret`	Shared secret for authenticating the interface	Text

The secret is stored in plain text in the configuration. Treat the global.config accordingly and do not pass on excerpts from it.

​Creating the file

​Who reads the file

​Common

​Conversions

​ProductDataFieldInjection

​Subsection +InjectData

​Subsection +SetData

​Patterns for ProductPattern-List

​SpecialUserCodes

​SpecialW2PConditions

​Values for Type

​SubShopMapping

​TopSeller

​ChargeLabel

​ChargeLabelValues

​VoucherNumberCharacters

​Sections for imports and third-party systems

​CustomerImportPro

​ProductImportPro

​ImportCharsetConvertMap

​FuturaECS

​Further sections

​TaxCases

​PaymentBruteForceProtection

​ProductDataJSONInterface

​CustomOfferAPI

Creating the file

Who reads the file

Common

Conversions

ProductDataFieldInjection

Subsection +InjectData

Subsection +SetData

Patterns for ProductPattern-List

SpecialUserCodes

SpecialW2PConditions

Values for Type

SubShopMapping

TopSeller

ChargeLabel

ChargeLabelValues

VoucherNumberCharacters

Sections for imports and third-party systems

CustomerImportPro

ProductImportPro

ImportCharsetConvertMap

FuturaECS

Further sections

TaxCases

PaymentBruteForceProtection

ProductDataJSONInterface

CustomOfferAPI