Mapping Repositories

• How do I open a mapping repository card?
• What are the different types of repositories?
• What additional notes should I know about Repository - Record Pool?
• How do I use a Repository - XML Node?
• How do I use a Repository - Buffer Table?
• How do I use a Repository - JSON Token?
• How do I use a Repository - SharePoint List?

Tip

Summary: This chapter discusses the different types of repositories that are available in the COSMO Data Integration Framework. It provides instructions on how to open a mapping repository card, as well as an overview of the different types of repositories such as Table, Record Pool, XML Node, Buffer Table, JSON Token, and SharePoint List.

A Repository defines the storage or the retrieval of a Record. It is valid throughout the entire Mapping process. The contents of the Repository can be accessed at any given point. When requesting a value (field), a Record should be opened first.

To open a mapping repository card

Tip

Summary: This chapter provides instructions for how to open a mapping repository card and describes the different types of repositories available in the COSMO Data Integration Framework.

1. Choose Repositories on the Mapping Version Card.
2. Choose the Edit action to open the Repository Card page where further field settings can be made for the respective Repository Type. Hover over a field to read a short description.

Options for types of repositories

Tip

Summary: The Table repository provides access to all tables in the Microsoft Dynamics 365 Business Central database. Depending on the setting, also temporary records or records of other companies can be read and written. The Company Name and Company of Partner fields require the COSMO Data Integration Framework Intercompany extension.

The following describes the Types of Repositories options in more detail:

• Table – A Table in the current Microsoft Dynamics 365 Business Central database.
• Record Pool – A Record Pool (as the basis) for storing values.
• XML Node – A Node Name inside an XML file.
• Buffer Table – A special transposed table that can be used by custom event file reading and writing.
• JSON Token - A JSON Object or a JSON Array item in the JSON repository.
• SharePoint List - COSMO Data Integration Framework is able to communicate with a Microsoft SharePoint easily. It is possible to write and read data from SharePoint lists like any other table.

Repository - Table

The Table repository provides access to all tables in the Microsoft Dynamics 365 Business Central database. Depending on the setting, also temporary records or records of other companies can be read and written.

The Company Name and Company of Partner fields require the COSMO Data Integration Framework Intercompany extension.

Note

The source code of a Trigger (Table or Field) is executed in the context of the current Company. Trigger should not be avoided for company-specific tables.

Repository - Record Pool

Tip

Summary: The Record Pool repository allows users to pass all recorded data sets of a Record Pool in a loop.

With the Record Pool repository, all recorded data sets of a Record Pool can be passed in a loop. All Record Pool Entries are considered always for the selected Partner. In addition to the defined fields in the Repository Card page, more setting options can be made in the actual Record Pool. For more information, see Record Pools.

Important

When processing the Mapping Lines for a Record Pool Repository, it is only possible to use Line Actions Find, Modify (only for Sub Line Action = Current Record) and Delete (only for Sub Line Action = Current Record). An Insert to a Record Pool is not possible. With Modify and Delete, the corresponding Record of the Table is modified.

Additional notes

The Permitted Record Frequency field determines how often records can be processed. The options are:

• Unrestricted – Each Record can be processed infinitely; default option
• Once – A Record can be processed one time per Partner.

The setting in this field is transferred from the Record Pool. If the Permitted Record Frequency field for the Record Pool is set to Once, the mapping settings are overruled.

For more information, see Records Frequency.

The Record Frequency Error Handling field describes how a record is handled if the Permitted Record Frequency is exceeded. The options are:

• Skip Record
• Create Warning and Skip
• Create Warning and Process
• Create Error

Note

For the Skip Record option, the Record Pool Entry is also set to Processed.

This field is only editable for Permitted Record Frequency = Once.

For more information, see Records Frequency.

The Use Partner Matrix field specifies if entries inside the Partner Matrix should be noted.

Note

The Record Pool Entry is set to Processed even if a Record does not exist in the Partner Matrix.

The Company of Partner field requires the COSMO Data Integration Framework Intercompany extension.

Mapping Filters for record pools only work for Record Pool Entries of the Record Pool type, not for entries of the XML Node type. There's a notification when entering a mapping filter for a record pool mapping line.

Repository - XML Node

• How do I save or load an XML repository?
• How do I define the name of the first node in an XML file?
• How do I open the Repository Fields page?
• How do I define the type of a field node?
• How do I create the field structure of an XML node?
• How do I transfer fields when exporting records to XML?
• How do I define document lines as child nodes of the document header?

Tip

Summary: This chapter explains how to use the XML Node repository in the COSMO Data Integration Framework. It describes the structure of an XML file and how to save or load this XML Repository. It also explains how to create a field structure of the XML Node, based on the field structure of another Repository, and how to use the XML Parent Node to define document lines as Child Nodes of the document header.

When running the Mapping, an XML file is stored in memory. Choose the Process action to save or load this XML Repository. When transferring Partner Messages, the XML file is attached and transferred as well. This provides the transport of data through databases.

The structure of an XML file is user-defined. With the XML Repository Root Node Name field on the Advanced Settings FastTab in a Mapping Version, the name of the first node (Envelope) can be defined. The standard value is database.

Choose the Show Fields action to open the Repository Fields page for the selected XML Node.

Field values are either independent nodes (text or CData) below the Row Node or attributes (of the row or another field). In the XML Child Type field, the type of the field node can be defined. If the Field Attribute option is selected, manually enter the field name for managing the attribute in the XML Attribute for Field field.

Note

Field Name must be a valid XML Node Name. The entered value is not checked.

On the Repository Card or Repositories page, choose the Create Field Structure action to create the field structure of the XML Node, based on the field structure of another Repository. This is especially useful for the Transfer-Fields function or in order to provide the lookups for Record Pools within the Mapping configuration.

With the selection of Transfer-Fields, all related data types (for example decimal, date) are automatically attached to each XML Node when exporting records to XML. This also allows a simple import of records from XML. Thereby, binary fields are automatically converted to Base64. When exporting records to XML without Transfer-Fields, a binary field is written as text. The conversion into Base64 must be selected within settings for Mapping Fields (see Conversions). With this, a SharePoint field of type HTML can be written as non-Base64-converted.

Use the XML Parent Node to define document lines as Child Nodes of the document header. This allows a hierarchical structure of the XML repository. Filters apply to the hierarchy.

Note

Be careful when naming Fields and Child Row Nodes are overlapping; otherwise, problems can occur when reading an XML file.

Repository - Buffer Table

• What is a Repository - Buffer Table?
• How do I export and import the Buffer table?

Tip

Summary: This chapter shows how to use the Buffer Table repository. It explains the concept of the Buffer Table repository and how to access the fields in the repository by creating fields in the repository's field structure and by implementing a custom transport type.

The Buffer Table repository can be used like a normal table in mapping configuration. CSV tables can have an undefined amount of fields. The buffer table is based on the Line No., Field No., and Value fields. All values of the CSV table will be copied into separate buffer records, like a transposed table. Reading all records (values) with Line No. = 1 will retrieve all fields for the first record of the CSV.

To access the fields, create fields (starting by 1) in the repository's field structure. Export and Import the Buffer table by implementing a custom transport type, choosing Partner Transport Type = Your-Custom-Type (for more information, see Transport Type - Options to transmit messages).

Repository - JSON Token

• How do I open a mapping repository card?
• What are the options for types of repositories?
• What is the structure of a JSON file?
• What is the JSON Repository Root Token Type?
• How do I open the Repository Fields page for a selected JSON Token?
• What is the structure of a Parent JSON Token Type and JSON Token Name?
• How do I create the field structure of a JSON Token?
• How do binary fields get converted to Base64?
• What is the purpose of the Parent JSON Token?
• What should I be careful of when naming fields and child row properties?

Tip

Summary: This chapter provides an overview of the different types of repositories available for use in the COSMO Data Integration Framework, specifically focusing on the JSON Token Repository. It explains how to open a mapping repository card, the different options for types of repositories, and how to create a field structure for a JSON Token.

When running the Mapping, a JSON file is stored in the memory. Choose the Process action to save or load this JSON Repository. When transferring Partner Messages, the JSON file is attached and transferred as well. This provides the transport of data through databases.

The structure of a JSON file is user-defined. With the JSON Repository Root Token Type field on the Advanced Settings FastTab in a Mapping Version, the type of the root token inside the file can be defined. The standard value is Array.

Choose the Show Fields action to open the Repository Fields page for the selected JSON Token.

Field Values are separate JSON Properties below the line token. The JSON Token Type field defines the type of the token. Together with the Parent JSON Token field and the JSON Token Name field different structures will result. The JSON Token Name can be empty.

Parent JSON Token Type	JSON Token Type	JSON Token Name	Structure
Object	Array	<Not empty>	{"name":[{"field":"value"}]}
Object	Array	<Empty>	{"0":[{"field":"value"}]}
Object	Object	<Not empty>	{"name":{"field":"value"}}***
Object	Object	<Empty>	{"0":{"field":"value"}}***
Array	Array	<Not empty>	[{"name":[{"field":"value"}]}]
Array	Array	<Empty>	[{"field":"value"}]
Array	Object	<Not empty>	[{"name":{"field":"value"}}]***
Array	Object	<Empty>	[{"field":"value"}]

Note

*** Multiple records will necessarily be written inside the same object. Multiple records can only be managed as objects inside of arrays.

Note

Field Name must be a valid JSON Token Name. The entered value is not checked.

On the Repository Card or Repositories page, choose the Create Field Structure action to create the field structure of the JSON Token, based on the field structure of another Repository. This is especially useful for the Transfer-Fields function or in order to provide the lookups for Record Pools within the Mapping configuration.

With the selection of Transfer-Fields, all binary fields are automatically converted to Base64. When exporting records to JSON without Transfer-Fields, a binary field is written as text. The conversion into Base64 must be selected within settings for Mapping Fields (see Conversions).

Use the Parent JSON Token to define document lines as Child Tokens of the document header. This allows a hierarchical structure of the JSON repository. Filters apply to the hierarchy.

Note

Be careful when naming Fields and Child Row Properties are overlapping; otherwise, problems can occur when reading a JSON file.

Repository - SharePoint List

• How do I configure SharePoint list?
• What are the authentication options available for SharePoint?
• How do I set up the Folder Variable Key?
• What is the purpose of the Skip GetListItem field?
• How do I add a custom query text to the CAML filter query?

Tip

Summary: The COSMO Data Integration Framework app can read and write data from SharePoint lists. It offers two different types of authentication: OAuth 2.0 and SharePoint App. An additional NTLM authentication is available for OnPrem environments. The Folder Variable Key field defines the key of a variable used as current folder in the SharePoint list. The Skip GetListItem field is a performance setting that can lower the amount of web service calls. The Query Node Postfix field enables to add a custom query text to the CAML filter query used against the SharePoint to get list items.

The COSMO Data Integration Framework app can read and write data in SharePoint lists. The Web URL field defines the URL of the site where the list is added. If your full list URL is https://my.sharepoint.com/sites/demo/dif/Lists/MyList/AllItems.aspx, the web URL would be https://my.sharepoint.com/sites/demo. After adding the authentication, use the List GUID lookup to select the list from the SharePoint web. All available fields are synchronized.

COSMO Data Integration Framework offers two different options of authentication towards SharePoint. The Credential Type = OAuth 2.0 enables the OAuth 2.0 Application Code field and requires a valid OAuth Application configuration. The Credential Type = SharePoint App enables the SharePoint Realm (Azure Tenant ID), SharePoint Target Host, SharePoint App Client ID, and SharePoint App Client Secret fields. All fields must be filled correctly to establish a connection to SharePoint.

For OnPrem environments, the COSMO Demo SharePoint NTLM extension app can be installed. The Credential Type = NTLM will be available and the NTLM Username, NTLM Password and NTLM Security Protocol fields are enabled and required.

The Folder Variable Key field defines the key of a variable used as current folder in the SharePoint list. For example, you can set this field to a value MyFolderVariable, that is further defined in your mapping by a Mapping Variable as MyFolderVariable = '2021/my-sub-folder/my-sub-sub-folder' at runtime. A mapping will read and write SharePoint list items only in the designated folder. If no folder is used, leave this field empty. To create a folder in a SharePoint list, insert a list item with the mapping fields FSObjType = 1 and BaseName/Title/FileLeafRef = name of the folder. Afterwards, set the variable defined in the Folder Variable Key field to the relative path of the created folder, to create items inside of the folder.

The Skip GetListItem field is a performance setting. After modification or insertion of a SharePoint list item, an additional GetListItem can be skipped. If the modified or inserted item is not used further, this can lower the amount of web service calls, and thereby process a mapping faster.

The Query Node Postfix field enables to add a custom query text to the CAML filter query, used against the SharePoint to get list items. The value is added after the cumulated mapping fields. An example value could be <And><Eq><FieldRef Name='MyField'><Value Type='Text'>My Value</Value></Eq></And>.

Feedback

Submit feedback for this page .