1. Data Management
  2. Connectivity Studio
  3. Design
  4. Set up documents
  5. Set up internal documents

Set up Staging document

Use a Staging document to read data from or write data to the staging table.


Application Consultant Application Consultant Start Start Set up document - Staging Set up document - Staging Use a Staging document to write data to or read data from the staging table. You can use the staging table to validate data before you actually process it. For example, you can validate received data before you import it into D365 F&SCM. You can do these validations automatically or manually, depending on the chosen handler. If the validations are: Not met, the journal gets the status Rejected. The found errors or warnings are added to the journal. You can solve these data errors or warnings before further processing the data. Met, the journal gets the status Approved and can be picked up for further processing. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. Click New. 4. Define a meaningful name for the document. Example: If the document is used for a sales integration, you can use names like 'Sales - Order' or 'Sales - Invoice'. In the Document field, type a value. Note: Best practice: In the document name, do not use the: - Application: Use the Application field to define the applicable application. - Document type: Use the Document type field to define the applicable document type. 5. In the Project field, enter or select a value. 6. Define the applicable application for the document. For a Staging document, for example, select a 'D365 F&SCM' or 'Staging' application. In the Application field, enter or select a value. Note: You can only select an application that is defined for the applicable project. You can define project applications on the Projects page. 7. In the Document types field, select 'Staging'. 8. Sub-task: Set Properties. 9. Expand the Properties section. 10. To improve performance when processing a lot of records, you can use paging. For paging, the records are split over several threads which run these records in parallel batch tasks. Define the number of records to be processed by one batch task. In the Query page size field, enter a number. Note: You can use this calculation to define the number to be entered: Query page size = Total number of records / Number of available threads. 11. On export, if you start the message run manually, you can have the standard D365 F&SCM query page shown before the message is run. You can use this query page to define more-detailed ranges. Select Yes in the Prompt field. Note: If the message is run in batch, the standard D365 F&SCM query page is not shown, and an error is logged. 12. In the Journal type field, type a value. 13. In the Number sequence field, enter or select a value. 14. Define the staging journal table. You can select one of the predefined staging tables. If you do not use EDI, use the predefined 'BisStagingBufferOrderJournal' table. If you have set up a custom staging table in the right way, you can select it here as well. In the Journal table field, enter or select a value. Note: If you use the predefined 'BisStagingBufferOrderJournal' table, on the Lines view, in the Records section, enter the 'BisStagingBufferTable' as record table. You define the record relations with the Parent record field. So, do not define relations on the Relations tab. 15. In the Inventory document flow field, select an option. 16. On creation of an EDI staging journal, when line validations are not met, the staging journal can be split into two staging journals. If the staging journal is split, separate staging journals are created with the: - Approved lines. So, these lines can be processed further. - Rejected lines. You can only split a staging journal if the journal table of the document is one of these EDI staging tables: - BisEdiStagingTransferOrder - BisEdiStagingPurchOrder - BisEdiStagingSalesOrder - BisEdiDelforStagingJournal - BisEdiStagingInventoryOrder Select Yes in the Split on error field. Note: If 'Split on error' is 'Yes', also define the 'Split percentage'. 17. Define the maximum percentage of rejected lines for which a staging journal can be split. Define a percentage between 0 and 100. In the Split percentage field, enter a number. Note: If the percentage of rejected lines is higher than the 'split percentage', the staging journal is not split. So, only one staging journal is created with the journal status 'Rejected'. 18. Sub-task: Set (custom) handler. 19. Expand the Custom section. 20. In the Handler field, enter or select the desired handler class. 21. Sub-task: Set advanced features. 22. Expand the Advanced section. 23. Select the desired query type: Standard: To select the data, only one D365 F&SCM query is created for the document. Custom: To select the data, a separate query is created for each document record. The Custom query feature offers an alternative approach to data retrieval. Unlike the standard query, with the Custom query, you can: Join data across different companies. Control queries more precisely with the Group by function. Limit the selection to the first record only for complex queries. Use fields from ancestor records in record relations. In the Query type field, select an option. Note: Try to use the standard query unless the standard query does not give the desired results. So, only use the custom query if required to get a specific query result. 24. Close the page. Add document records - Internal document Add document records - Internal document To each document, add the data records to be exchanged. For internal documents, set up the records in line with how the data is structured and named in D365 F&SCM. This topic explains how to add records to documents of these types: D365 F&SCM, Journal, or Staging. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired document of one of these types: D365 F&SCM, a journal type, or Staging. 4. Click Edit. 5. In the Record section, click Add line. 6. In the Record field, type a value. 7. In the Record table field, enter or select a value. 8. In the Parent record field, enter or select a value. 9. Select Yes in the Combine with parent record field. 10. In the Join mode field, select an option. 11. Select Yes in the History field. 12. Sub-task: Set record details. 13. Expand the Line details section. 14. A document record can result in a selection of several matching records. In some cases, you only want to select one record for a document record. With the Custom query, you can use the Select first record function. Selecting only one record improves the performance. Select Yes in the First record only field. Note: This field is available only if for the document, on the header, the Query type is 'Custom'. 15. With the Custom query, for internal documents, you can use Group by to summarize, condense, and analyze data during export. Select Yes in the Group By field. Note: This field is available only if for the document, on the header, the Query type is 'Custom'. Manage document record setup - Internal documents

Manage document record setup - Internal documents

You have several options to manage the document record setup for internal documents.

You can:
  • Change the sequence of the records.
  • View the D365 F&SCM table relations.
  • View where a record is used.
  • Check or change the table relations.
  • Define the data querying order.
  • Define the range of data to be queried.
  • Validate the record setup.

 Select fields Select fields You can add a selection of table fields to a record. You can select fields from the D365 F&SCM table that is defined in the Record table field. This is mainly applicable to internal documents. However, you can also use this to quickly set up fields for external file-based documents. When the field selection is added to the record, review and complete the properties of the added fields. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired document. 4. Click Edit. 5. In the Records section, in the Record list, find and select the desired record. 6. Click Select fields. 7. Sub-task: Define filter. 8. In the Table name field, enter or select a value. 9. Select Yes in the Show system fields field. 10. Select No in the Show inherited fields field. 11. Usually, you add fields to an internal document record with the type as defined in the table setup. However, you can add all selected fields with the type set to String. Select Yes in the Create as string fields field. Note: This field is only available for internal documents. 12. Sub-task: Select fields. 13. Click Select the fields of a specific group to open the drop dialog. 14. In the Field group name field, enter or select a value. 15. Click OK. 16. Click Select all. 17. Click Deselect all fields. 18. Click Select mandatory. 19. Select the Selected check box for the desired fields. 20. Click OK. Copy fields Copy fields You can copy fields from a record of another document. You can use this, for example, to save setup time if you use a specific record in several documents.You can only copy fields:From a record with the Record table defined.To a record with no fields.As a result, the full field setup is copied from the selected record to the current record. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired document. 4. Click Edit. 5. In the Record section, in the Record list, find and select the desired record. 6. Click Copy fields. 7. In the Record field, select the desired record from another document. Note: You can only select a record with the same Record table defined as the current record. 8. Click OK. 9. Close the page. Add document record fields - Internal documents Add document record fields - Internal documents To each document record, add the data fields which values must be exchanged. For internal documents, set up the fields in line with naming in D365 F&SCM. For internal documents, make sure the fields have the same type as in D365 F&SCM. This topic explains how to add records to documents of these types: D365 F&SCM, Journal, or Staging. If fields are already selected for or copied to the record, you can review and complete the setup for these fields. To do so, skip step 6. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired document of one of these types: D365 F&SCM, a journal type, or Staging. 4. Click Edit. 5. In the Records section, in the Record list, find and select the desired record. 6. On the Fields tab, click New. 7. In the Field name field, enter or select a value. 8. In the Record table field field, enter or select a value. 9. Select the Key field check box. 10. In the Mandatory field, select an option. 11. In the Length field, enter a number. 12. If you use a Custom query for the document, you can use Group by. Group by has several types of functions: Group by function: Groups records based on the value of one or more fields. Aggregate functions: An aggregate is done based on all records in the group. Avg: Calculates the average value of the field. Min: Gets the lowest value of the field. Max: Gets the highest value of the field. Sum: Totals the field values. Count: Counts the records in the group. None: The field is ignored by the Group by function. In the Group By field, select an option. Note: This field is available only if for the: Document, on the header, the Query type is 'Custom'. Document record, in the Line details, Group by is set to 'Yes'. Manage document record field setup

Manage document record field setup - Internal documents

You have several options to manage the document record field setup for internal documents.
You can:

  • Change the sequence of the fields.
  • View where a field is used.
  • Clean up unused fields.
  • Create a related record.

 Set up staging display options Set up staging display options For a document of type Staging, for each document record, you can set up the display options for the related staging journal.Use the display options to define which fields of the record are shown and editable on the Data tab of the staging journal. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired document of type Staging with Journal table 'BisStagingBufferOrderJournal'. 4. Click Edit. 5. On the ActionPane, on the Design tab, click Staging display options. 6. Sub-task: Initialize fields. 7. Click Initialize options. 8. Refresh the page. 9. Sub-task: Select fields. 10. In the list, find and select the desired record. 11. Click Select fields. 12. Click Select all. 13. Click Deselect all fields. 14. Select the Selected check box. 15. Click OK. 16. Sub-task: Add field manually. 17. Click Add line. 18. In the Record field field, select the desired field to be added. 19. Select the Editable check box. 20. Select the Hide check box. 21. Sub-task: Define field display sequence. 22. In the list, find and select the field to be moved up. 23. Click Move up. 24. In the list, find and select the field to be moved down. 25. Click Move down. 26. Close the page. 27. Close the page. Set up staging validations Set up staging validations For each document record, you can define data validations to be done when a data record is inserted in the staging journal. Found validation errors, warnings, or dependencies are stored as validation errors for the relevant staging journal. For a Staging document, these standard validation classes are available: Validation class Description BisValidationFieldisMantadory This class checks if the field is filled. The arguments are: FieldValue and Type. The validation is met if the field has a valid value. For example, for date fields, the value 0 is not valid. BisValidationReferenceExists This class checks if a record exists in the defined table. The validation is met if at least one record exists in the table. The arguments are KeyFieldName or KeyFieldValue (only define one of these arguments) and TableName. For example, you can check if a customer exists in the CustTable. If the customer does not exist, a validation error is reported. BisValidationMdmDifference This class if differences exist between the data that is send from the source to the MDM staging journal and the current data in the target. This validation defines what happens with MDM staging journal lines with data differences. You can only use this class if you use: The Master data management staging journal. Data comparison on the MDM staging journal. For more information, refer to Monitor MDM staging journal. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired document of type Staging with Journal table 'BisStagingBufferOrderJournal'. 4. Click Edit. 5. On the ActionPane, on the Design tab, click Staging display options. 6. Click the Validation tab. 7. Sub-task: Set up validation. 8. Click New. 9. You can set up a staging validation that applies to: All companies in your D365 F&SCM environment. To do so, do not define a company. A specific company. To do so, define the desired company. In the Company accounts ID field, enter or select a value, or clear the value. Note: The Company accounts ID field is available only if the 'Shared staging validation' feature is activated in the Connectivity studio parameters. In this case, the Validation tab only shows the shared validation setup (no company defined) and the validation setup for the current company. If the 'Shared staging validation' feature is inactive, the staging validation setup applies only to the company in which it is set up. 10. In the Validation class field, enter or select a value. 11. In the Exception behavior field, select an option. 12. In the Type field, select an option. 13. In the Number field, enter a number. 14. In the Text field, type a value. 15. Click Save. 16. Sub-task: Set up validation arguments. 17. In the Record field field, enter or select a value. 18. In the Constant field, type a value. 19. Select the Active check box. 20. Close the page. 21. Close the page. Validate connectivity setup

Validate connectivity setup

If you open a form or save (changes to) the setup of a key element in Connectivity studio, the setup is validated automatically. If errors are found in the setup, an error icon   is shown. You can click the icon to show the related error messages.

You can also manually start an automated test to check for errors in the setup. As a result, the errors found are shown. Also, the error icons are shown where applicable.
When errors are found, you can try to fix these errors automatically.
You can check and auto-fix errors for these key elements in Connectivity studio:
Key element Check
Projects When automatically checked, only the project setup is checked, and not the related setup like messages and connectors. When started manually, the full project setup is checked.
Documents The document setup is checked, including the document records setup.
Document records Only the document records setup is checked.
Messages The message setup is checked, including the data synchronization setup and message mapping.
Message - Data synchronization setup Only the data synchronization setup is checked.
Message mapping Only the message mapping is checked.
Message business events A check is done if a business event is created for the message business event. Also, a check is done to see if the target fields and source fields match the related document setup.
Connectors Only the connector setup is checked.
Web services The web service setup is checked, including the data synchronization setup.
Web service - Data synchronization setup Only the data synchronization setup is checked.

In this flow, in the activity steps, as an example, the validation is done for documents.

 End End

Activities

Name Responsible Description

Set up document - Staging

Application Consultant
Use a Staging document to write data to or read data from the staging table.
You can use the staging table to validate data before you actually process it. For example, you can validate received data before you import it into D365 F&SCM. You can do these validations automatically or manually, depending on the chosen handler. If the validations are:
  • Not met, the journal gets the status Rejected. The found errors or warnings are added to the journal. You can solve these data errors or warnings before further processing the data.
  • Met, the journal gets the status Approved and can be picked up for further processing.

Add document records - Internal document

Application Consultant

To each document, add the data records to be exchanged. For internal documents, set up the records in line with how the data is structured and named in D365 F&SCM.

This topic explains how to add records to documents of these types: D365 F&SCM, Journal, or Staging.

Manage document record setup - Internal documents

Application Consultant

You have several options to manage the document record setup for internal documents.

You can:
  • Change the sequence of the records.
  • View the D365 F&SCM table relations.
  • View where a record is used.
  • Check or change the table relations.
  • Define the data querying order.
  • Define the range of data to be queried.
  • Validate the record setup.

Select fields

Application Consultant

You can add a selection of table fields to a record. You can select fields from the D365 F&SCM table that is defined in the Record table field.

This is mainly applicable to internal documents. However, you can also use this to quickly set up fields for external file-based documents.

When the field selection is added to the record, review and complete the properties of the added fields.

Copy fields

Application Consultant

 		You can copy fields from a record of another document. You can use this, for example, to save setup time if you use a specific record in several documents.
You can only copy fields:
  • From a record with the Record table defined.
  • To a record with no fields.
As a result, the full field setup is copied from the selected record to the current record.

Add document record fields - Internal documents

Application Consultant

To each document record, add the data fields which values must be exchanged. For internal documents, set up the fields in line with naming in D365 F&SCM.
For internal documents, make sure the fields have the same type as in D365 F&SCM.

This topic explains how to add records to documents of these types: D365 F&SCM, Journal, or Staging.
If fields are already selected for or copied to the record, you can review and complete the setup for these fields. To do so, skip step 6.

Manage document record field setup

Application Consultant

 		You have several options to manage the document record field setup for internal documents.
You can:
  • Change the sequence of the fields.
  • View where a field is used.
  • Clean up unused fields.
  • Create a related record.

Set up staging display options

Application Consultant

 		For a document of type Staging, for each document record, you can set up the display options for the related staging journal.
Use the display options to define which fields of the record are shown and editable on the Data tab of the staging journal.

Set up staging validations

Application Consultant

For each document record, you can define data validations to be done when a data record is inserted in the staging journal.

Found validation errors, warnings, or dependencies are stored as validation errors for the relevant staging journal.
For a Staging document, these standard validation classes are available:
Validation class Description
BisValidationFieldisMantadory This class checks if the field is filled. The arguments are: FieldValue and Type. The validation is met if the field has a valid value. For example, for date fields, the value 0 is not valid.
BisValidationReferenceExists This class checks if a record exists in the defined table. The validation is met if at least one record exists in the table. The arguments are KeyFieldName or KeyFieldValue (only define one of these arguments) and TableName. For example, you can check if a customer exists in the CustTable. If the customer does not exist, a validation error is reported.
BisValidationMdmDifference

This class if differences exist between the data that is send from the source to the MDM staging journal and the current data in the target. This validation defines what happens with MDM staging journal lines with data differences.

You can only use this class if you use:

  • The Master data management staging journal.
  • Data comparison on the MDM staging journal.

For more information, refer to Monitor MDM staging journal.

Validate connectivity setup

Application Consultant

If you open a form or save (changes to) the setup of a key element in Connectivity studio, the setup is validated automatically. If errors are found in the setup, an error icon   is shown. You can click the icon to show the related error messages.

You can also manually start an automated test to check for errors in the setup. As a result, the errors found are shown. Also, the error icons are shown where applicable.
When errors are found, you can try to fix these errors automatically.
You can check and auto-fix errors for these key elements in Connectivity studio:
Key element Check
Projects When automatically checked, only the project setup is checked, and not the related setup like messages and connectors. When started manually, the full project setup is checked.
Documents The document setup is checked, including the document records setup.
Document records Only the document records setup is checked.
Messages The message setup is checked, including the data synchronization setup and message mapping.
Message - Data synchronization setup Only the data synchronization setup is checked.
Message mapping Only the message mapping is checked.
Message business events A check is done if a business event is created for the message business event. Also, a check is done to see if the target fields and source fields match the related document setup.
Connectors Only the connector setup is checked.
Web services The web service setup is checked, including the data synchronization setup.
Web service - Data synchronization setup Only the data synchronization setup is checked.

In this flow, in the activity steps, as an example, the validation is done for documents.

See also

Provide feedback