2.10.2. External Systems

External systems are other Nectainium environments with which message exchange is configured. You can add a connection between systems to later configure message exchange between them.

Example: You can set up one environment on a company's local network and another with external access, then configure message exchange between them.

2.10.2.1. Configure message exchange with an external system

The exchange configuration consists of the following steps:

1. Make sure both systems meet the requirements for message exchange.
2. Set the current system code
3. Add a connection to the external system
4. Configure system #1
5. Configure system #2
6. Initiate exchange between the configured systems

2.10.2.1.1. System requirements

To configure integration between two systems, make sure they meet one of the following requirements:

• Both systems are on the same RabbitMQ server. This is the easiest scenario to configure.

  System A ⟷ RabbitMQ server ⟷ System B

• Both systems each have their own separate RabbitMQ server. They must then be configured to interact via the Shovel plugin.

  System A ⟷ RabbitMQ server A ⟷ RabbitMQ server B ⟷ System B

• Both systems, where only one of them uses RabbitMQ. This is the most complex scenario and requires the @unitybase/messaging package. That is, one system can be Nectainium and the other can be any system capable of sending HTTP requests and working with JSON data format.

  System A ⟷ RabbitMQ server ⟷ System B (without RabbitMQ)

Note:

Once you have confirmed that your systems meet one of the listed scenarios, contact your platform system operator to configure the interaction between the two systems at the server level.

2.10.2.1.2. Set the current system code

Before configuring integration between two systems, you need to set the current system code. This only needs to be done once. Once your system has configured integrations with other systems, you will not be able to change the system code.

1. In the navigation panel, select the Studio 1 workspace.

2. Select the Integration 2 shortcut group, then select the External Systems 3 shortcut.

3. In the toolbar, select the This System Code 4 button.

4. In the Code 1 field, enter the desired system code, then select the Save 2 button.

2.10.2.1.3. Add a connection to an external system

1. In the navigation panel, select the Studio 1 workspace.

2. Select the Integration 2 shortcut group, then select the External Systems 3 shortcut.

3. In the toolbar, select Create 4.

4. Fill in the fields 1 using the hints in the table below, then in the toolbar select Save 2.

The external system message types table will then be displayed.

Field name	Description
Code*	Enter the existing code of the external system.
Name*	Enter a clear, descriptive name for display in the system: • The name must clearly identify the external system • It is recommended to use the full system name
Description	Enter a brief description of the external system's purpose: • Specify the main purpose of the integration • Describe the specifics of interaction with this system • Add any useful information for other administrators

Note:

Fields marked with "*" are required.

2.10.2.1.4. Configure system #1

1. In system #1, create an external system message type for sending data to the external system:

   1.1. In the navigation panel, select the Studio 1 workspace.
   1.2. Select the Integration 2 shortcut group, then select the External System Message Types 3 shortcut.
   1.3. In the toolbar, select Create 4.
   

   1.4. Fill in the fields 1 using the hints in the table below, then in the toolbar select Save 2

Field name	Description
Code*	Enter a unique identifier for the external system message type. • The code must be unique. • The code must be short (typically up to 10 characters). • Use only Latin letters and digits. ℹ️ Note: editing the "Code" field is only possible for external systems that are not used in any existing document types in the system.
Name*	Enter a clear name for display in the interface. • Specify the clear purpose of the message. • Use any characters, including Cyrillic. Examples: "Outgoing order message", "Incoming invoice" ℹ️ Note: you can set alternative names for different languages. To do this, in the "Name" field, select the icon and fill in the fields for other languages. Then select the "Apply" button.
Direction*	Select To external system — to send data. ℹ️ Note: the direction selection determines the further settings

---

"To external system" settings

Field name	Description
External system	Select the required system from the list of available ones. Make sure the selected system is already configured.
Transport configuration	In this field, you can use a script to set additional settings for the message.

---

"From external system" settings

Field name	Description
External system	Select the required system from the list of available ones. Make sure the selected system is already configured.
Schema	The field is used to build the receiving schema, which describes the document types and attributes to be transferred. The schema can be saved to a file or uploaded from a file.
Action for unprocessed messages*	Actions to be performed on a message if it cannot be processed. Select one of the available actions: • Return to queue for reprocessing — to retry processing the message • Place in quarantine — for manual analysis and correction • Discard — to delete the message without the ability to recover it 💡 Tip: for important data, use quarantine.
Action on format error*	Select the action in case of data format mismatch: • Return to queue for reprocessing — if the error may be temporary • Place in quarantine — for analysis of format issues • Discard — if the data is guaranteed to be in the wrong format 💡 Tip: start with quarantine to analyze typical errors.
Action on other errors*	Define the system's response to unexpected errors: • Return to queue for reprocessing — to retry on system failures • Place in quarantine — for detailed analysis of non-standard errors • Discard — if the error is critical and cannot be corrected 💡 Tip: for new integration types, start with quarantine.

Note:

Fields marked with "*" are required.

2. In system #1, go to the document type to configure the exchange.

   2.1. In the navigation panel, select the Studio 1 workspace.
   2.2. Select the Document Types 2 shortcut, then select the document type 3 from which you want to send data.
   

   2.3. Go to the Exchange 1 tab.
   2.4. In the actions menu, find the section with system #2 code ("QA") 2, then enable the toggle for the message type created in the previous step 3.
   2.5. In the toolbar, select Save 4

3. In system #1, while in the same document type as in the previous step, configure the actions after which data from the document type will be sent to the external system.

   3.1. Go to the States tab, then enable the toggle for the required document state.
   3.2. Select the state activated in the previous step, then in the Actions section select the Add button.
   

   3.3. In the Action type field, select Event.
   

   3.4. Fill in the remaining fields using the hints from the Add action table.
   3.5. Select the Save button.
   

   3.6. In the toolbar, select Save

4. In system #1, while in the same document type as in the previous step, add to the document type form the attributes you want to send to the external system.

   4.1. Go to the Constructor 1 tab, in Designer 2 mode.
   4.2. From the attributes menu, drag the desired attributes onto the form 3.
   4.3. In the toolbar, select Save 4

   Note:

   The form can contain any number of attributes — not all of them need to be used for exchange.

5. In system #1, while in the same document type as in the previous step, configure the events that will initiate data exchange between the systems.

   5.1. Go to the Events tab, then select Add handler.
   

   5.2. In the Event 1 field, select the event created in the third step of this guide — "Action execution: Send (New)".
   

   5.3. In the Handler type 2 field, select "Send document to external system".
   

   5.4. In the External system 3 field, select the name of system #2.
   

   5.5. In the Message type 4 field, select the message type you created in the first step of this guide.
   

   5.6. Select the Add 5 button.
   

   5.7. In the toolbar, select Save.

6. In the added handler, add the attributes that will be sent to the external system. These can be all the attributes you added to the document form in step #4.

   6.1. Select the added handler, then select the button to add an attribute of the appropriate type:

   • Add standard attributes — to add standard platform attributes located in the "Document" folder.
   • Add custom attributes — to add custom attributes, i.e. those created by the platform user.
   • Add roles — to add document roles you want to transfer.

   6.2. In the Add attributes field, check the boxes next to the same attributes you placed on the form in the Constructor tab.

   6.3. Select the Add attributes button.

7. For complex attributes, configure additional data transfer parameters. This allows you to precisely control what information is sent along with the attribute.

   7.1. In the table with the added columns, in the Actions column, select the icon.

   7.2. In the menu that appears, select the required additional parameters:

   • For attributes linked to a directory: Enable the toggles for the directory attributes whose data you want to transfer.
   • For attributes of the "Document image" type, you can enable or disable the transfer of electronic signatures.
   Note:

   The set of available parameters depends on the attribute type.

8. Once the attributes have been added and configured, select the Download schema button and save the file. In the following steps, you will upload this schema to system #2 to conveniently transfer the attribute settings.

System #1 configuration is complete. Proceed to configuring system #2.

2.10.2.1.5. Configure system #2

1. In system #2, create a message type for receiving from the external system.

   a. In the navigation panel, select the Studio 1 workspace.
   

   b. Select the Integration 2 shortcut group, then select the External System Message Types 3 shortcut.
   

   c. In the toolbar, select Create 4.
   

   d. Fill in the fields 1 using the hints in the table below, then in the toolbar select Save 2

Field name	Description
Code*	Set the message code — it must be the same as the message type code you created in system #1.
Name*	Enter any desired name. • Specify the clear purpose of the message. • Use any characters, including Cyrillic. ℹ️ Note: you can set alternative names for different languages. To do this, in the "Name" field, select the icon and fill in the fields for other languages. Then select the "Apply" button.
Direction*	Select From external system — to receive data.
External system	Select system #1 from the list.
Schema	Select the Upload from file button, then select from your device the schema file you downloaded from system #1 (in step #7).
Action for unprocessed messages*	Select Place in quarantine — for manual analysis and correction of important data.
Action on format error*	Select Place in quarantine — for analysis of format issues.
Action on other errors*	Select the system's response to unexpected errors: Place in quarantine — for detailed analysis of non-standard errors.

Note:

Fields marked with "*" are required.

2. In system #2, go to the document type that will receive the attributes.

   a. In the navigation panel, select the Studio 1 workspace.
   b. Select the Document Types 2 shortcut, then select the required document type 3 to which you plan to send data.
   

   c. Go to the Exchange 1 tab.
   d. In the actions menu, find the section with system #1 code 2, then enable the toggle for the message type you created in the first step of this guide 3.
   e. In the toolbar, select Save 4.

3. In system #2, while in the same document type as in the previous step, add to the document the attributes whose values you want to receive from the external system.

   a. Go to the Constructor 1 tab, in Designer 2 mode.
   b. From the attributes menu, drag the desired attributes onto the document form 3.
   c. In the toolbar, select Save 4

4. In system #2, while in the same document type as in the previous step, configure the events that will initiate data exchange between the systems.

   a. Go to the Events tab, then select Add handler.
   

   b. In the Event 1 field, select the event created earlier — "Receiving a document from an external system: System name".
   

   c. In the Handler type 2 field, select "Set attribute values".
   

   d. Select the Add 3 button.
   

   e. In the toolbar, select Save

5. In the added handler, add the attributes that will be received from the external system. You can add all the attributes you added to the document form in step #4.

   a. Select the added handler, then select the button to add an attribute of the appropriate type:

   • Add standard attributes — to add standard platform attributes located in the "Document" folder.
   • Add custom attributes — to add custom attributes, i.e. those created by the platform user.

   b. In the Add attributes field, check the boxes next to the attributes into which data from the external system will be received.

   c. Select the Add attributes button.

6. In the same handler of system #2, establish a link between the attributes of the two systems.

   a. In the table with the added columns, in the Actions column, select the icon.

   b. In the Message field 1 field, select from the list the attribute from system #1 that you want to link.
   

   c. Select the Save 2 button.

   d. Repeat this step for each added attribute.

7. Go to the Correlation tab to configure additional conditions for data exchange. This is needed if you use the same message type for two or more document types. You can then add a correlation condition that tells the system which of the two document types the message should be sent to.

8. In the toolbar, select Save.

System #2 configuration is complete. Proceed to the next section to initiate exchange between the configured systems.

2.10.2.1.6. Initiate exchange between the configured systems

1. In system #1, create a document whose data you want to transfer to system #2.

   a. In the navigation panel, select the Documents 1 workspace.
   b. Select the Documents 2 shortcut.
   c. In the toolbar, select Create 3.
   

   d. In the Document type 1 field, select the document type you configured for exchange in step #2 during system #1 configuration.
   

   e. In the Short description 2 field, enter a brief description of the document.
   

   f. Select the Create 3 button.

   Note:

   If the required document type is not available in the Document type dropdown, return to the document type settings, go to the Access tab, and specify the users who should have access to create documents.

2. Fill in the document with the data you want to transfer to system #2.

   a. In the same document you created in the previous step, fill in all the desired attributes with data 1.
   

   b. In the toolbar, select Save 2.
   

   c. In the toolbar, select the Refresh icon.
   

   d. In the toolbar, select the Send button.
   

   e. In the Confirm action window, select the Yes button.
   

   If the send is successful, you will see the message "Action 'Send' completed successfully" in the upper right corner of the screen.

   After that, a document with the attributes transferred from the system #1 document will be created in system #2.

   Note:

   If you make changes to the document in system #1 and select the Send button again, the data in the system #2 document will be updated.

2.10.2.2. Example: configuring exchange between two systems

Let's walk through a specific example of how to configure data exchange between two systems.

Consider the following scenario:

We have two systems:

• system #1 (with the code "QACAB")
• system #2 (with the code "QA")

Our goal: transfer 5 different fields (attributes) from a document in system #1 to system #2.

2.10.2.2.1. Prepare the systems

Before starting configuration, contact the platform system operator to set up the interaction between the two systems at the server level.

2.10.2.2.2. Add a connection to the external system

1. In the navigation panel, select the Studio 1 workspace.

2. Select the Integration 2 shortcut group, then select the External Systems 3 shortcut.

3. In the toolbar, select Create 4.

4. In the Code field, enter the code of system #2 — "QA", in the Name field enter a clear descriptive name, then in the toolbar select Save 2

2.10.2.2.3. Configure system #1

1. In system #1, create a message type for sending to the external system.

   1.1. In the navigation panel, select the Studio 1 workspace.
   1.2. Select the Integration 2 shortcut group, then select the External System Message Types 3 shortcut.
   1.3. In the toolbar, select Create 4.
   

   1.4. In the Code 1 field, set the message code, for example "HR_VacationOrder".
   1.5. In the Name 2 field, enter any desired name.
   1.6. In the Direction 3 field, select To external system.
   1.7. In the External system 4 field, select the name of system #2 — QA — from the list.
   1.8. In the toolbar, select Save and Close 5.

2. In system #1, go to the document type from which you want to send data, and configure the exchange.

   2.1. In the navigation panel, select the Studio 1 workspace.
   2.2. Select the Document Types 2 shortcut, then select the document type 3 from which you want to send data.
   

   2.3. Go to the Exchange 1 tab.
   2.4. In the actions menu, find the section with system #2 code ("QA") 2, then enable the toggle for the message type "Vacation Order" 3.
   2.5. In the toolbar, select Save 4

3. In system #1, while in the same document type as in the previous step, configure the actions after which data from the document type will be sent to the external system.

   3.1. Go to the States tab.
   

   3.2. Enable the toggle for the New state, so that when a new document is created, a button for sending data to the external system appears.
   

   3.3. Select the state activated in the previous step, then in the Actions section select the Add button.
   

   3.4. In the Action type field, select Event.
   

   3.5. Fill in the remaining fields using the hints from the Add action table.
   3.6. Select the Save button.
   

   3.7. In the toolbar, select Save

4. In system #1, while in the same document type as in the previous step, add to the document the attributes that will be sent to the external system.

   4.1. Go to the Constructor 1 tab, in Designer 2 mode.
   4.2. From the attributes menu, drag the desired attributes onto the form 3.
   4.3. In the toolbar, select Save 4.
   

   Note:

   The form can contain any number of attributes — not all of them need to be used for exchange.

5. In system #1, while in the same document type as in the previous step, configure the events that will initiate data exchange between the systems.

   5.1. Go to the Events 1 tab, then select Add handler 2.
   

   5.2. In the Event 1 field, select the event created in the third step of this guide — "Action execution: Send (New)".
   

   5.3. In the Handler type 2 field, select "Send document to external system".
   

   5.4. In the External system 3 field, select the name of system #2 — "QA".
   

   5.5. In the Message type 4 field, select "HR_VacationOrder (Vacation Order)" — the one created in the first step.
   

   5.6. Select the Add 5 button.
   

   5.7. In the toolbar, select Save

6. In the added handler, add the attributes that will be sent to the external system. In our example, we add all the attributes placed on the document form in step #4.

   6.1. Select the added handler, then select the Add attributes button to add an attribute of the appropriate type.
   

   6.2. In the Add attributes list, check the boxes next to the same attributes placed on the form in the Constructor tab.
   

   6.3. Select the Add attributes button.

7. For complex attributes, configure additional data transfer parameters. This allows you to precisely control what information is sent along with the attribute.

   7.1. In the table with the added columns, in the Actions column, select the icon.

   7.2. In the menu that appears, select the required additional parameters:

   • For attributes linked to a directory: Enable the toggles for the directory attributes whose data you want to transfer.
   • For attributes of the "Document image" type, you can enable or disable the transfer of electronic signatures.
   Note:

   The set of available parameters depends on the attribute type.

8. Once the attributes have been added and configured, select the Download schema button and save the file. In the following steps, you will upload this schema to system #2 to conveniently transfer the attribute settings.

System #1 configuration is complete. Proceed to configuring system #2.

2.10.2.2.4. Configure system #2

1. In system #2, create a message type for receiving from the external system.

   a. In the navigation panel, select the Studio 1 workspace.
   

   b. Select the Integration 2 shortcut group, then select the External System Message Types 3 shortcut.
   

   c. In the toolbar, select Create 4.
   

   d. Fill in the fields 1 using the hints in the table below, then in the toolbar select Save 2
   

Field name	Description
Code*	Set the message code — "HR_VacationOrder". It must be the same as the message type code created in system #1.
Name*	Enter any desired name, for example "Vacation Order".
Direction*	Select From external system.
External system	Select system #1 — "QACAB" — from the list.
Schema	Select the Upload from file button, then select from your device the schema file you downloaded from system #1 (in step #7).
Action for unprocessed messages*	Select Place in quarantine — for manual analysis and correction of important data.
Action on format error*	Select Place in quarantine — for analysis of format issues.
Action on other errors*	Select Place in quarantine — for detailed analysis of non-standard errors.

Note:

Fields marked with "*" are required.

2. In system #2, go to the document type that will receive the attributes.

   a. In the navigation panel, select the Studio 1 workspace.
   b. Select the Document Types 2 shortcut, then select the required document type 3 to which you plan to send data.
   

   c. Go to the Exchange 1 tab.
   d. In the actions menu, find the section with system #1 code ("QACAB") 2, then enable the toggle for the message type "Vacation Order" 3.
   e. In the toolbar, select Save 4

3. In system #2, while in the same document type as in the previous step, add to the document the attributes whose values you want to receive from the external system.

   a. Go to the Constructor 1 tab, in Designer 2 mode.
   b. From the attributes menu, drag the same attributes as in system #1 onto the form 3.
   c. In the toolbar, select Save 4

4. In system #2, while in the same document type as in the previous step, configure access so that the required users can create documents based on the created document type.

   a. Go to the Access 1 tab.
   b. Select the Add 2 button.
   

   c. Add the Create documents and View documents access types.
   

   d. Add the user who should have access to perform these actions to these access types.

5. In system #2, while in the same document type as in the previous step, configure the events that will initiate data exchange between the systems.

6. In the automatically added handler, add the attributes that will be received from the external system. In our example, we add all the attributes placed on the document form in step #4.

   a. Go to the Events 1 tab.
   

   b. Select the automatically added handler "Receiving a document" 2, then select the Add attributes 3 button to add an attribute of the appropriate type:
   

   c. In the Add attributes list, check the boxes next to the attributes into which data from the external system will be received.
   

   d. Select the Add attributes button.
   

7. In the same handler of system #2, establish a link between the attributes of the two systems.

   a. In the table with the added columns, in the Actions column, select the icon.
   

   b. In the Message field 1 field, select from the list the attribute from system #1 that you want to link.
   

   c. Select the Save 2 button.
   

   d. Repeat this step for each added attribute.
   

8. Go to the Correlation tab to configure additional conditions for data exchange. This is needed if you use the same message type for two or more document types. You can then add a correlation condition that tells the system which of the two document types the message should be sent to.

9. In the toolbar, select Save.

System #2 configuration is complete. Proceed to initiating exchange between the configured systems.

2.10.2.2.5. Initiate exchange between the configured systems

1. Create a document in system #1 and fill it with the data you want to transfer to system #2.

   a. In the navigation panel, select the Documents 1 workspace.
   b. Select the Documents 2 shortcut.
   c. In the toolbar, select Create 3.
   

   d. In the Document type 1 field, select the document type you configured for exchange in step #2 during system #1 configuration.
   e. In the Short description 2 field, enter a brief description of the document.
   f. Select the Create 3 button.

2. Fill in the document with the data you want to transfer to system #2.

   a. In the same document you created in the previous step, fill in all the desired attributes with data 1.
   

   b. In the toolbar, select Save 2.
   

   c. In the toolbar, select the Refresh icon.
   

   d. In the toolbar, select the Send button.
   

   e. In the Confirm action window, select the Yes button.
   

   If the send is successful, you will see the message "Action 'Send' completed successfully" in the upper right corner of the screen.

   After that, a document with the attributes transferred from the system #1 document will be created in system #2.

   Note:

   If you make changes to the document in system #1 and select the Send button again, the data in the system #2 document will be updated.

2.10.2.3. Manage exchange results for external systems

This section provides step-by-step instructions for monitoring, correcting, and managing data exchanged between your platform and external systems. You will learn how to identify and fix exchange errors, resend messages after corrections, and manage detected duplicates.

2.10.2.3.1. View exchange errors

Message quarantine is a registry that contains error messages that occurred while receiving data from external systems. This tool helps administrators identify and resolve data exchange issues.

1. In the navigation panel, select the Administration 1 workspace.

2. Select the Maintenance tools 2 shortcut group, then select the Message quarantine 3 shortcut.

3. Select the error whose details you want to view.

4. On the General tab, you can view the following error details:

   • External system — this field contains the code, name, and URL of the external system with which the message exchange was supposed to take place.
   • External system message type — the external system message type used during the exchange between the systems.
   • Message ID — the unique identifier of the specific message.
   • Type — the error category that occurred during the exchange. Errors can be of the following main types:
     • Format error — if the schema is configured incorrectly.
     • Found Duplicates Document — if duplicate checking is enabled.
     • Unknown exception — for all other errors; details can be viewed in the "Details" field.
   • Reason — a brief description of the cause of the error.
   • Details — a detailed technical description of the error. Contains a stack trace showing the sequence of operations that led to the error.

5. Go to the Parts tab if you want to view the specific components of the message.

   If you want to download a part of the message in JSON format to your device, select the Save to file button.

2.10.2.3.2. Fix an error and resend the message

If an error occurred during message exchange, you can fix it and try to send the message again.

1. In the navigation panel, select the Administration 1 workspace.

2. Select the Maintenance tools 2 shortcut group, then select the Message quarantine 3 shortcut.

3. Select the error whose details you want to view.

4. Go to the Parts tab.

5. Select the message part you want to modify, then select the Upload from file button to update the required parts of the message using data from a file that you can upload from your device.

6. In the Confirm action window, select Yes.

7. Select from your device a JSON file in which you have resolved the issue that caused the error.

8. In the toolbar, select the Return to queue button. The system will try to process the message again, and the record will disappear from the registry.

Note:

To delete the error record without retrying to send the message, select the Discard button.

2.10.2.3.3. Manage duplicates among exchange results

1. Log in to system #2 (the one to which you sent the data).

2. Open the document type in which you configured exchange with the other system.

3. Go to the Events tab.

4. Enable the Apply document duplicate control rules toggle.

5. Once the toggle is enabled, all new documents arriving from system #1 to system #2 will be checked for duplicates. If duplicates are detected, such documents will appear in the Message quarantine shortcut and will be assigned the document type "Found Duplicates Document".

6. If you want to edit the duplicate documents, in the Document link section, follow the link to the duplicate documents and edit them.

or

6. You can also ignore the presence of duplicates and still create a document from the received data. To do this, in the toolbar select the Return to queue ignoring duplicates button.