Documentation

3.2.1. Scopes

Scopes define the context of the data used within a template. For example, if the scope is set to Invoice, the template can access all fields available on the Invoice object.

Scopes determine which records are considered when generating a document. Each template must have at least one Primary Scope, which refers to the Salesforce ID of the primary source record.

Every template scope is linked to a specific template record, and defines which data is available within that template. Scopes reflect the data model of the connected Salesforce org and serve several purposes.

To create the primary scope, click on the "New" button in the scopes section and select 'Primary'.

X

In addition to the primary scope, you can create field scopes and list scopes within the primary scope by clicking on the 'Create Child Scope' button. These types of scopes are known as children of the primary scope, meaning that they refer to data within the object of the primary scope. You can also create a free scope by clicking on the 'New' button in the scope data record.

X

• Field scopes refer to lookup fields of the object and the data of the objects to which the lookup points (e.g. an account).
• List scopes refer to data from the object's lists (e.g. all contacts under the account defined in the field scope).
• Free scopes refer to all data records in Salesforce and do not need to be linked to a field or list scope (e.g. all products in Salesforce).

For Field and List scopes, you must define a parent record (e.g. your primary scope). Free Scopes do not need a parent record.

Record Rules

In the case of list and free scopes, you can define 'Record Rules' to exactly filter the entries of the scope you want to include.

There are three types of record rules:

• Filter Record Rule
• Limit Record Rule
• Order Record Rule

Filter Record Rules

This type of record rule is used to filter records from the scope based on the evaluation of a condition on a certain field. The 'Field Name' and 'Value' are compared using the selected 'Operator', and only the records for which the condition evaluates to true will be considered for the scope.

X

Limit Record Rules

With a limit record rule, you can specify how many records should be included. Simply create a limit record rule and enter the amount of records included in the 'Value' field.

X

Order Record Rule

With order record rules you can define wether records should be sorted in a specific order based on a specific field of the scope object. XRSF lets you define multiple order record rules, which can be ordered themselves using the 'Priority' field.

X

3.2.2. Data Configurations

With Data Configurations, you can populate the attributes of your invoice with data from your Salesforce Organization, specifically from your scopes. You can create a data configuration via the 'Configure' button at the top right.

X

After clicking 'Configure', a new window opens where you now can specify configurations.

X

Here you can now add child configurations via the 'Add' button. You can specify the attribute that should be populated and the scope from where the data originates.

The data configurations follow the same structure as you have defined in the corresponding standard. With nested arguments, search for the values via the configure button of each attribute.

X

If you leave the scope empty, you can use data from all of your defined scopes via merge fields, specify static input or choose pre-defined variables (e.g. current date, current user ID).

X

In this example, we populate the "ID" attribute with the value of the "Account ID" field from the "OrderAccount" Scope. In addition, we do not want to use data from a scope for the "DueDate" attribute, so we left the scope field empty and can now choose a value from the picklist under "Pick Variable".

Once you have specified all data configurations, click on 'Save' and you will get back to the template overview.

3.2.3. Field Updates

You can also configure field updates within the Template, which lets you update fields on your source record after an invoice is created, such as setting a “Send Date” to today. In field updates you can also set a condition under which the field update is applied, using the ‘Operator’, ‘Condition Value’ and New Value‘ ’fields. If the given condition is not satisfied, the field update will not be executed.

In this example we want to implement a Field Update, such that the invoice status gets updated to ‘Created’ when the file is created and only if the status was formerly ‘Draft’.

X

3.2.4. Additional Configuration for Embedded Templates

When using embedded Templates, there are a couple of extended configurations you can specify. These only apply to the PDF document that will be created and thus have no influence on XML Templates.

XMP Requirements

One key field for embedded Templates is XMP Metadata. This field is crucial for ensuring that your generated PDF complies with PDF/A-3B and Factur-X/ZUGFeRD standards. XMP (Extensible Metadata Platform) is a standardized XML format for embedding metadata in PDF files. This metadata provides information about the document’s structure, origin, and compliance level, and is used by consumers and validation tools to assess conformance.

To support different metadata configurations, there is a 'XMP Requirement' picklist where you can choose between Custom and ZUGFeRD.
If you select Custom, you can manually enter your own XMP metadata.
If you select ZUGFeRD, the metadata will be automatically set to a predefined, standard-compliant value.

You can set the XMP Requirement in the creation window of the Template, or later on in the template overview.

X

The metadata block is embedded in the PDF and enables tools (e.g., KOSIT or ZUGFeRD validators) to interpret the PDF as a structured hybrid invoice, where the visual representation is linked to a machine-readable XML inside the PDF.

Important: The correctness and completeness of the XMP block are critical for interoperability and legal compliance, especially in countries (like Germany) that mandate standard formats like XRechnung or ZUGFeRD.

Document Generation

Additionally, you will need to upload a Microsoft Word Template in the Files section. This template acts as a blueprint for the document creation and will be used for every invoice that is created using this template. This is mandatory, as no document will be created without a blueprint in the files section.

For embedding data from your Salesforce Organisation into the Word document, you can use merge fields. Please note that the use of merge fields in Word documents is different to the use of merge fields in Salesforce. You can find a more detailed description of the use of merge fields in the next chapter of this documentation.

Also, you can specify a naming pattern that should be applied to the documents that will be created. Similar to the 'Naming' field, you can specify this pattern in the 'Embedded Naming' field.

3.2.5. Merge Fields

In XRSF, a distinction must be made between merge fields that are used in the document itself and those that can be used in scopes and field updates.

Merge fields in Microsoft Word

The syntax of the merge fields is based on the merge field logic of Microsoft Word (used, for example, when creating form letters).

A merge field is structured as follows:

{ MERGEFIELD ScopeName.Fieldname \* MERGEFORMAT }

with ScopeName the API name of the Scope and Fieldname the API name of the respective field. The "MERGEFIELD" is mandatory at the beginning of every mergefield, "MERGEFORMAT" however acts as a placeholder for optional formatting specifications (e.g. for dates, time, Upper- or Lowercase). Mergefields must be inserted with the keyboard shortcut CTRL + F9.

For displaying every entry of a list scope, you will need to use a slightly different syntax. The syntax is as follows:

{ MERGEFIELD TableStart:SectionName }

* Here you can input text that should be displayed for every element in the list scope *

{ MERGEFIELD TableEnd:SectionName }

with SectionName the API name of the list scope.

In this example, we want to display all contacts from our list 'contacts' with their first and last name:

X

Merge fields in Salesforce

Merge fields in Salesforce can be referenced by the following syntax:

{ !ScopeName.FieldName }

Similar to merge fields in word, there is a slightly different syntax when using list scopes:

{TableStart:sectionName}

* Here you can input text that should be displayed for every element in the list scope *

{TableEnd:sectionName}

However, there is a slight difference to this syntax when using merge fields in the field updates. As field updates are always restricted to a defined scope, merge fields can be referenced just by the fieldname (instead of {!ScopeName.FieldName}, we can just use {!FieldName} ).

3.3.1. Mapping Conditions

In the mapping conditions, you can define conditions that must be satisfied for a mapping to be executed. A mapping condition can be either based on the file itself or based on Salesforce data (Object). You can create a new mapping condition by clicking 'New' in the mapping conditions section.

X

Note: When creating multiple mapping conditions, watch out when using multiple conditions based on the same field. In theory, it is possible to create conditions such that the mapping will never be executed.

3.3.2. Further configurations

Many sections of a Mapping are similar to those of a Template. Scopes, Data Configurations and Field Updates can be implemented in exactly the same way as in the templates.

One major difference of a Mapping are the target objects.

Target Objects

Target objects can be created in addition to scopes. They are specifically designed for processing incoming invoices and are used to perform specific actions on Salesforce objects. To create a new target object, click ‘New’ in the ‘Target Objects’ section.

X

An interface for creating a target object will open. Here you can specify the name of the target object, the API name of the desired object, and the associated mapping. You can also choose which operation should be performed on this object. There are four options:

• Insert: New data records are created.
• Read: The data is only read; no changes are made to data records.
• Update: Existing data records are updated.
• Upsert: New data records are inserted or existing ones are updated if a matching data record already exists.

Once you have filled the fields, click 'Save' and your target object will be created. As with the scopes, you can define the specific operations that should be performed on a target object in the Data Configurations.

3.3.3. Testing a Mapping

Once the mapping has been configured, XRSF offers the option to test the mapping before activation without making any actual changes to your Salesforce organization. To test a mapping, click on the ‘Test’ button in the mapping record.

X

After clicking, a window will open in which you must now select a record for the test. Of course, you can only select a record that corresponds to your primary scope. Simply enter the name of the record in the search field, or leave the search field blank to see all available records.

X

Select a record from the list, click ‘Choose’, and then select the file you want to use for the test in the next step.

X

When you click ‘Create’, a job is created to simulate the process and show what would happen based on your current mapping configuration. As mentioned before, no changes are made at this point.

If you want to actually execute the mapping as part of the test and make changes in Salesforce, click ‘Apply’ to open an evaluation screen and then click ‘Evaluate’ in that screen. This will execute the mapping logic as in a live scenario and make changes in Salesforce. By clicking ‘Visualize’, you can also see the XML body of your created invoice.

X

X

If everything works as you expect, you can now activate the mapping by clicking ‘Activate’ in the mappings record. Once a mapping is activated, it will be executed automatically when a document is uploaded to a record of the Primary Scope type and all mapping conditions are met.