1. Data Management
  2. Connectivity Studio
  3. Design
  4. Testing and troubleshooting
  5. Troubleshooting

Troubleshooting messages

When a message doesn't run successfully, you can troubleshoot the message.
You have several options to troubleshoot a message. You can, for example:
  • Validate the message setup.
  • Run a message for testing and troubleshooting purposes.
  • Analyze the message history.
  • Analyze the file history, if the message has an Azure file storage connector with file actions.
  • Analyze the tracer, if you have used the tracer on the message run.
Common issues on the message are:
  • Field mapping sequence: Make sure the fields are mapped in the same sequence as shown on the related form in D365 FO.
  • Mapping conditions and field conditions: Conditions limit the records that are processed. So, if records are skipped unexpectedly, check if conditions are defined.
  • Key field setup: Key fields are used to find and update records. If records are not updated unexpectedly, verify if the correct fields are marked as key fields.


Application Consultant Application Consultant Start Start Copy message? Copy message? Copy message Copy message You can create a copy of a message. For example, to troubleshoot a failing message that is already in operation, you can copy the message. So, you do not disrupt the operational data. Procedure 1. Click Connectivity studio Integration Design. 2. On the Message tab, in the list, find and select the desired message. 3. Click Edit. 4. Click Copy. 5. In the Project field, enter or select a value. 6. In the New name field, type the name for the message copy. 7. In the Copy documents field, select the desired option. 8. In the Source document field, type a value. 9. In the Target document field, type a value. 10. Click OK. Validate message 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 found errors 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 if the target fields and source fields match with 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.

 Do you test an import message  and need a file with test data? Do you test an import message  and need a file with test data? Add file to Working folder Add file to Working folder If you want to test an import message with an external file-based source document, you need a file with test data to be imported. This file must be available in the Working folder that is defined for the source connector.You can add the test data file to the Work folder in these ways:Upload the file to the Working folder.Copy or move a file from the Archive or Error folder to the Working folder. Procedure 1. Click Connectivity studio Integration Design. 2. On the Message tab, in the list, find and select the desired import message. 3. Click Edit. 4. Sub-task: Upload data file to Working folder. 5. On the Action Pane, click Design. 6. Click Upload to Work. Note: The Upload to Work option is also available on the Connector page. 7. Click OK. 8. Sub-task: Copy or move data file to Working folder. 9. Click File explorer. 10. In the tree, select 'the Archive folder or the Error folder'. 11. In the list, find and select the desired file. 12. Click Copy or Move. 13. In the tree, select 'the Working folder'. 14. Click Paste. 15. Click OK. Run message for testing purposes Run message for testing purposes You can run a message for testing and troubleshooting purposes. You can find and analyze the results in the: Message history. File history if the message has an Azure file storage connector with file actions. Tracer if you have used the tracer on the message run. Note: If the message setup is validated, a message run can still result in errors or give an unexpected result. In this case, you can choose to store all processed records in the message history for analysis purposes. To do so, before the test run, on the message header, set the Store history field to 'Yes'. When the issue is solved, do not forget to set the Store history field back to 'No'. Procedure 1. Click Connectivity studio Integration Design. 2. On the Message tab, in the list, find and select the desired message. 3. Click Run. 4. You can use a tracer to register what a message does when it is run. When a message has run using the tracer, you can review the registered actions in the tracer. Usually, you use this to find issues in the message run. Select Yes in the Use tracer field. Note: You can use the tracer in combination with the test quantity. 5. To test a message, you can run it for a defined number of records only. In this way, testing is quicker and with less history or tracer records to be reviewed. You can use this, for example, to test a message in the design phase. If the message is used to: - Export data, the records are taken from D365 FO, as defined by the source document. - Import data using an external file-based document as source document, the records are taken from the file as defined in the message run dialog. - Import data using an external ODBC document as source document, the records are taken from the external database. Example: If the test quantity is 2, only the first two records found are used. In the Test quantity field, enter a number. Note: You can use the test quantity in combination with the tracer. 6. In the File name field, enter or select a value. Analyze message history

Monitor message history

You can review and analyze the history of message runs that have run with errors. You can investigate these errors and take the appropriate actions to solve the errors. If the errors are solved, you can re-run the message run.

To monitor the message history, use the Connectivity studio integration operations workspace.

 

@videoref:CS7

 Analyze file history

Monitor file history

You can review and analyze the file history of message runs for messages with an Azure file storage connector. All actions that are done to the related file, are registered in the file history.
Registered file actions are the:
  • Standard file actions related to the Working, Archive, Error, and Split folders. For example, on import, a file is read from the Working folder and when successfully processed, it is moved to the Archive folder. Both the 'read' and the 'move' action are registered.
  • Additional file actions as set up for the Azure file storage connector.
You can monitor the file history from the Connectivity studio Integration operations workspace.

 Did you use  the tracer? Did you use  the tracer? Analyze tracer Analyze tracer When you run a message for testing purposes, you can use a tracer to register what the message does when it is run. When the message has run using the tracer, you can review the registered actions in the tracer. Usually, you use this to find issues in the message run. Procedure 1. Click Connectivity studio Integration Design. 2. In the list, find and select the desired record. 3. Click Tracer. 4. In the tree, select 'the source record that you want to review'. 5. In the action list, find and select the desired action. 6. Expand the Mapping section. 7. The Source record section shows the values of the source record fields. In case of an: - Export, all fields of the source record table in D365 FO are shown. So, also the not-mapped table fields are shown. - Import, all fields are shown, that are defined for the applicable record in the source document. So, also the not-mapped document record fields are shown. Expand the Source record section. Note: In case of an export message, you can show or hide the system fields of the source record table. 8. The Target record section shows the values of the target record fields. In case of an: - Import, all fields of the target record table in D365 FO are shown. So, also the not-mapped table fields are shown. If a field value is changed, also the previous value is shown. - Export, all fields are shown, that are defined for the applicable record in the target document. So, also the not-mapped document record fields are shown. Expand the Target record section. Note: In case of an import message, you can show or hide the system fields of the target record table. 9. Expand the Effected by section. 10. Close the page. Did you copy the message  before you started  troubleshooting? Did you copy the message  before you started  troubleshooting? Merge message Merge message You can troubleshooted a failing message using a copy of that message. When you have made changes to the message copy to solve the issue, the same changes must be applied to the original message. To do so, you can merge the message copy with the original message. When you merge a message (source) with another message (target), the: Target message settings are overwritten with the source message settings. Target message documents settings are overwritten with the source message documents settings. Note: Use this merge option carefully. You cannot undo the overwrite action. Procedure 1. Click Connectivity studio Integration Design. 2. On the Message tab, in the list, find and select the desired message. 3. Click Edit. 4. On the Action Pane, click Design. 5. Click Merge messages. 6. In the Target message field, enter or select the message which settings must be overwritten with the source message settings. 7. Click OK. 8. Click Yes. End End Yes No Yes No Yes No Yes No

Activities

Name Responsible Description

Copy message

Application Consultant

You can create a copy of a message. For example, to troubleshoot a failing message that is already in operation, you can copy the message. So, you do not disrupt the operational data.

Validate message 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 found errors 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 if the target fields and source fields match with 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.

Add file to Working folder

Application Consultant
If you want to test an import message with an external file-based source document, you need a file with test data to be imported. This file must be available in the Working folder that is defined for the source connector.
You can add the test data file to the Work folder in these ways:
  • Upload the file to the Working folder.
  • Copy or move a file from the Archive or Error folder to the Working folder.

Run message for testing purposes

Application Consultant

You can run a message for testing and troubleshooting purposes. You can find and analyze the results in the:

  • Message history.
  • File history if the message has an Azure file storage connector with file actions.
  • Tracer if you have used the tracer on the message run.
Note: If the message setup is validated, a message run can still result in errors or give an unexpected result. In this case, you can choose to store all processed records in the message history for analysis purposes. To do so, before the test run, on the message header, set the Store history field to 'Yes'. When the issue is solved, do not forget to set the Store history field back to 'No'.

Analyze message history

Application Consultant

You can review and analyze the history of message runs that have run with errors. You can investigate these errors and take the appropriate actions to solve the errors. If the errors are solved, you can re-run the message run.

To monitor the message history, use the Connectivity studio integration operations workspace.

 

Analyze file history

Application Consultant
You can review and analyze the file history of message runs for messages with an Azure file storage connector. All actions that are done to the related file, are registered in the file history.
Registered file actions are the:
  • Standard file actions related to the Working, Archive, Error, and Split folders. For example, on import, a file is read from the Working folder and when successfully processed, it is moved to the Archive folder. Both the 'read' and the 'move' action are registered.
  • Additional file actions as set up for the Azure file storage connector.
You can monitor the file history from the Connectivity studio Integration operations workspace.

Analyze tracer

Application Consultant

 		When you run a message for testing purposes, you can use a tracer to register what the message does when it is run. When the message has run using the tracer, you can review the registered actions in the tracer. Usually, you use this to find issues in the message run.

Merge message

Application Consultant

You can troubleshooted a failing message using a copy of that message. When you have made changes to the message copy to solve the issue, the same changes must be applied to the original message. To do so, you can merge the message copy with the original message.

When you merge a message (source) with another message (target), the:

  • Target message settings are overwritten with the source message settings.
  • Target message documents settings are overwritten with the source message documents settings.

Note: Use this merge option carefully. You cannot undo the overwrite action.

Analyze message history

Analyze file history

Provide feedback