Tutorial

1.Get started

This tutorial will give you a clear explanation on how to use Myddleware.

In this process, we will be connecting two solutions SuiteCRM and Prestashop as we go along. You can also follow this tutorial by using another application already linked to Myddleware like Salesforce, Magento…

To start, login to Myddleware and create your connectors to these solutions.

2.Connector

What is a connector ?

A connector is the object which allows Myddleware to connect to the solution (SuiteCRM or Prestahop for example,). This allows Myddleware to be able to read or to write into the solution.

Before we do anything, let’s first of all connect to Myddleware by entering your login and password :

myddleware_connection

 

 

 

 

 

Now, we start by creating a connectors to gives Prestashop and SuiteCRM access to Myddleware. So click on “Connector”  then “Create” :

connector_creation

Then select SuiteCRM in the solution list, add the parameters, name your connector, test it and if the connection is OK then click on “Save the connector” :

suitecrm_connector

Myddleware is now able and ready to read or to write into SuiteCRM.

In the same way, we will now create the connector for Prestashop :

suitecrm_connector

Now that you have created connectors, you can now create your first rule to transfer your data.

3.Rules

In this chapter we will create the first rule. The goal is to send all Prestashop customers to SuiteCRM accounts.

3.1.First rule

This chapter is about the rule creation. The rule is the root of Myddleware. It helps in guiding Myddleware on what to do with the data and how it should be transferred.

3.1.1.Select data

To create your first rule, click on “Rule” then “Creation” :

rule_select_solution

Then follow these stepts :

  1. Click on the source solution, it is the solution where Myddleware will read the data.
  2. Click on the target solution, it is the solution where Myddleware will write the data.
  3. Add a name to your rule.
  4. Select the connector you have created for the source solution.
  5. Select the connector you have created for the target solution.

Why there is a list for the connector ?

Myddleware allows you to have several connectors for a solution in case you want to connect several instances of the same solution or if you want to have different connectors with differents authorisations.

If all conncetors are still valid, you will be able to select the module corresponding to the date you want to transfer :

rule_select_module

We want to create an account in SuiteCRM for all customers in Prestashop. So select “The e-shop customer’s” Module for Prestashop and the “Accounts” module for SuiteCRM. Then click on “Go to the fields mapping”.

3.1.2.Map your fields

The field mapping allows you to indicate which data from you source application you want to transfer. Let’s start by adding the field email with a drag and drop :

email_mapping

This is a simple mapping with a unique drag and drop. You can do the same by transfering the fields “note” into the field “Description”, and the field “Website” into the field “Website”.

Now we will fix a value for the field account_type. We want  all accounts created by Myddleware via this rule to have the type “Customer”. To do that, click on “Create a formula” in the field “account_type” :

account_type_formula

Myddleware opens a pop-up to create your formula. You can use the dropdown list “Target” corresponding to all dropdown list in the target module. Select the value “Customer” in the section “Account type” of this list. Then click on the button formula_arrow to copy the right text in the formula area :

account_type_formula2

Finally click on “Confirm” to validate your formula :

account_type_formula3

We now want to send the firstname and the lastname of Prestashop to the account name of SuiteCRM. But there are 2 fields in Prestashop and only one in SuiteCRM. So we have to create another formula.

First step, drag fields “firstname” and “lastname” and drop it to the field “name”. You should have the account field looking like this :

account_name_formula

Then click on “Create a formula” in the field “name”.

account_name_formula2

Double click on a field to insert it in your fomula. So double click on “firstname” and “lastname”. But we want to add a space between the firstname and the lastname. To do that we use the “.” to concatenate some text. Your formula has to be this one: {firstname}." ".{lastname}

Finally click on “Confirm” to validate your formula :

account_name_formula3

The field ‘s mapping is finished, you can now test it to control your rule. Click on “Simulation” and “Test data”. Myddleware will get the last data in Prestashop and transform it with your own rule. Obviously, the test will only work if you have at least one data in your source application.

rule_test

We will talk about the tabs “Relationships” and “Filters” in another chapter.

3.1.3.Confirm the rule

To finish the creation of this rule, click on “Confirmation” :

rule_confirmation

You will see 2 parameters :

  1. Synchronization type : Depending on the solution, you could have choice to read new data created or all data created/modified in the source module. In our example, if you want to send new customer only created in Prestashop to SuiteCRM, then select “Create data only”. Otherwise  if you want to send customer modifications only in Prestashop to SuiteCRM, then select “Create and update data”. In our exemple we select “Create and update data”. This process will be based on the reference date you can set up, cf next chapter “Reference date”.
  2. Fields to avoid duplicates : You can select one of these fields if you want Myddleware to check if a record with the same value already exists in the target solution. If yes, Myddleware will only update this data and won’t create a duplicate. But to be able to duplicate with a field, the field must be present in the field mapping. In our example, we select “Email”.

Finally, you can click on “Confirm” to create the rule. After which the page with the detail of your rule should appear.

 

3.1.4.Rule detail

When you open a rule, all its details appear :

rule_detail

You will see a switch On/Off “Enabling the automatic synchronisation”. If this option is on, the job which synchronises data in background task will run this rule. If it is off, the background job will not run this rule. See the install guide if you want more information about this switch and how to set up the background task .

You will see these buttons :

  • Run the rule : It allows you to run the rule manually even if the switch “Enabling the automatic synchronisation” is off.
  • Edit the rule: It allows you to edit this rule.
  • Display the transfers : It allows you to see all the data transfers generated by this rule.
  • Delete the rule : It allows you to delete this rule.

You can also see all the tabs if you want to display the field ‘s mapping, the relationships, the filters or the parameters.

We will explain what  these parameters are in the next chapter.

3.1.5.Parameters

When you open a rule, click on the tab parameters :

rule_parameters

You will see 2 parameters on the left :

  • The reference date : This is the date Myddleware uses for data reading on source application. For example, if you set the date as todays, only data created or modified (depending on the mode of your rule) from today will be sent to your target application. If you want to migrate your data, you just have to put this date in the past. Then all data created/modified after this date will be read by Myddleware.
  • Deleting data : You can ask the system to delete the transferred data of your rule after x days. To use this functionality you have to set the background task “clear data”. See the install guide. For your information, this job will delete all data you have transferred for this rule, except the ids which are necessary for correct functioning of Myddleware.

On the left, is the option to simulate the number of data you want Myddleware to read depending on the reference date. The reference date can also be changed to your requirement, and then click on “Save” to simulate the number of transfer.

 

3.1.6.Run the rule

Your rule is now ready. If you didn’t change the reference’s date, you can create a new record in your source application.

Then return to your rule and click on “Run the rule” :

rule_run

When Myddleware return to the rule, an information message page appears. This is a link to redirect you to the task that Myddleware is running. it can be opened by clicking on it.

rule_task

In our example there is only on transfer, but you can send several data in one task.

The transfers can then be opened by clicking on “Display the transfers” :

rule_display_transfert

All transfers for this rule will become visible to you :

rule_list_transfers

You can then click on each one of the transfer to open:

rule_transfer_detail

You will then be able to see what Myddleware has read in the source application and what has been sent into the Target application.

You rule is at this stage up and running now. Let’s now create another rule to link to the one you already created.

3.2.1.Select data

To create a rule allowing two rules to relate with one another, both rules have to have the same connector. So let us  now create a new rule with the same applications and connectors using select modules “The customers orders” for Prestashop et “Opportunities” for SuiteCRM :

rule_rel_select_data

Then click on “Go to the fields mapping”.

3.2.2.Map your fields

You can now map your fields like this :

rule_relate_mapping

When we transfer a date, we often have to change the format because the solutions don’t have the same format. In this case, we want to transform the order date_add (fiomat datetime) into the opportunity closed date (format date). We then create the formula :
changeFormatDate( {date_add}, "Y-m-d H:i:s", "Y-m-d" )
Now put the field “valid” into one SuiteCRM field, we would need it when we want to filter.

We will now set up our first relationship.

3.2.3.Create relationship

We can create relationship in Myddleware to allow you to transfer a data model, not only a few data not linked.

We send the order in SuiteCRM and we have to link it to the account. But we have to retrieve the account id corresponding to the customer linked to the order in Prestashop.

To do that, we will link this new rule to the previous rule where we will be able to find the SuiteCRM account id.

rule_relationship

So we get the SuiteCRM “Account ID” from the rule “Customer” by using the customer_id in the Prestashop order.

3.2.4.Filter your data

You can also decide to filter the data you want to send into your target application, to do that click on the tab “Filters” :

rule_relate_filters

Here we want to keep only orders with the filed “valid” equal at 1, with only these order sent to SuiteCRM.

And now save your rule.

3.2.5.Run the rule

Now run your rule by clicking on “Run the rule” :

rule_relate_run

Open a transfer and you will see that Myddleware retrieve the “account id” from the “customer id” on the Prestashop order using the rule “Customer” previously created.

transfer_relate

In SuiteCRM, the opportunity is now linked to the account.

4.Transfer

The transfer is the record which store the data read in the source application, transformed by Myddleware and sent to the target application.

4.1.Search transfers

If you click on “Transfer => List”, you will be able to search tranfers. For example, you can search by rule and status :

transfer_search_1

You can search by creation/modification date, global status and ID too. You can use the character “%” in the search. For example,  if we search “%4d60%”, we will find all id which contain the string “4d60” :

transfer_search_2

Open a transfer now, and follow the detailed explanation of the transfer.

4.2.Transfer detail

There are 3 distinct parts in a transfer :

transfer_detail

 

  1. The header data :
    • Rule name and version related to this transfer
    • Status related to the global status (see below):
      • New (Open’) : When the transfer is created.
      • Create_KO (Cancel) : When the transfer creation failed.
      • Filter (Cancel) : When the transfer is filtered because of the rule filter.
      • Filter_OK (Open) : When the transfer is not filtered.
      • Filter_KO (Error) : When Myddleware failed to check if the transfer has to be filtered.
      • Predecessor_OK (Open) : When no other tranfer with the same source ID isn’t closed.
      • Predecessor_KO (Error) : When at least 1 transfer with the same source ID isn’t closed. Myddleware will wait until the others transfer has been successfully sent before sending this transfer. In our example, we can’t update the status of an order if this order hasn’t been created in the target application.
      • Relate_OK (Open) : When no other transfer relate to this transfer (in an other rule related) isn’t closed.
      • Relate_KO (Error) : When at least 1 transfer relate to this transfer (in an other rule related) isn’t closed. In our example, we can’t send an order if the customer hasn’t been sent.
      • Transformed (Open) : When the transfer is successfully transformed.
      • Error_transformed (Error) : When Myddleware failed to transform the tranfer.
      • Ready_to_send (Open) : When the transfer is ready to be sent to the target application.
      • Error_history (Error) : When Myddleware failed to get the data from the target applicaion, only when the transfer update data.
      • Send (Close) : When the transfer is successfully sent.
      • Error_sending (Error) : When Myddleware failed to sent the data to the target application.
      • No_send (Cancel) : When there is no identification between the data in the target application and the data Myddleware should sent. So Myddleware cancel the transfer.
      • Cancel (Cancel) : When the transfer is manually cancelled.
    • Mode indicate the mode of the rule related to the transfer:
      • 0 : The rule will create and update data to the target application.
      • C : The rule will only create data to the target application.
      • S : The rule will search data into the target application (no creation and no modification).
    • Type of the transfer :
      • C : The transfer create data to the target.
      • U : The transfer update data to the target.
    • Global status
      • Open : The transfer is still in process.
      • Cancel : The transfer has been cancelled.
      • Error : The transfer is locked and has an error.
      • Close : The transfer has been successfully sent.
  2. The detail of the data in 3 parts
    • Source : Data red in the source application
    • Target : Data sent to the target application
    • History : If the transfer update data in the target application, we get the data from the target application before we modify it.
  3. The logs with the transfer with its historic status

 

4.3.Manage a transfer in error

When a transfer is in error, you can modify it, by re sending it or cancelling it. To be able to modify the data, double click on target data, change the data and click on the validation icone :

transfer_error

Then try sending the data again to the target application by clicking on “Reload the transfer” or cancel it by clicking on “Cancel the transfer”.

 

4.4.Mass action

You can reload or cancel several transfer at the same time in the transfer list view.

Note: Only transfer in error can be reload or cancelled.

Select the transfer you want to reload or cancel and click on “Cancel transfers” or “Reload transfers” :

transfer_error_mass

We will discuss how to manage tasks in the next chapter:

5.Task

A task is an execution of the program which read data, manage all transfers not closed or cancelled from the source application, and then send them to the target application. This allows for many transfers to be carried out in one task.

To list the tasks, click on “Task” then on “List” :

tasks_list

Then open a task by clicking on its Id to see the detail of what happend during the execution of the task :

task_detail

If the task is still running (status Start), there will be option to click on 2 buttons :

  • Refresh : To refresh the page and see how the task is executing and when it is finished.
  • Stop task : To stop the task.

6.1.Relationships

In the example above, we showed you how to create relationship, keeping the same data model. Customer and order from Prestashop were sent to the Account and opportunities in SuiteCRM.

In the examples below you will learn how to create relationship with different data model :

  • One to many : The data from Prestahop in the module Customer will be sent to SuiteCRM in Account and Contact modules.
  • Many to one : The data from Prestashop in customer and address modules will be sent to SuiteCRM in the module Account.

6.1.1.Relationship one to many

Now let us create 2 rules with 1 module in the source application to be sent to 2 modules in SuiteCRM. We have already created the rule which send Prestashop customer to SuiteCRM accounts. Now we will re-use the same module Prestashop Customer, sending it to the SuiteCRM contacts.

Let’s create this rule :

rule_one_to_many_1

Go to fields mapping and map few fields like firstname, lastname, birthday or email.

Then open the tab “Relationship”. We want to link the contacts to their accounts already sent to SuiteCRM in a previous rule. In this scenario, Myddleware would have to find the SuiteCRM account ID in the previous rule and send it into the contact to link this contact and the account already created :

rule_one_to_many_2

Now save the rule and run it. Don’t forget to put the reference date in the past if you want to retrieve data already exiting in Prestashop.

And now open a transfer and you will discover Myddleware has found the right account to link to the contact.

rule_one_to_many_3

The id “1” is used for timing in the source data, first time for the contact and second time for the account. At this point, you just created your first relationship one to many, one customer to 2 records (contact and account).

6.1.2.Relationship many to one

Here we want to create 2 rules with 2 modules in the source application to be sent to 1 module in SuiteCRM. We have already created the rule which send Prestashop customer to SuiteCRM accounts. Now we want to send Prestashop customer addresses to SuiteCRM accounts.

Let’s create this rule :

rule_many_to_one_1

Go to fields mapping and map few fileds like address1, address2, city, postcode…

Then open the tab “Relationship”. We want to send adresses to the accounts already sent to SuiteCRM in a previous rule. In this case again as above, Myddleware would have to find the SuiteCRM account ID in the previous rule and update this account :

rule_many_to_one_2

Here we use ID Account, it is the ID id the target module of the current rule, so no transfer will create any data. This rule will only update data.

Now save the rule and run it. Don’t forget to put the reference date in the past if you want to retrieve data already exiting in Prestashop.

Now open a transfer and you will see that Myddleware has found the right account to updated :

rule_many_to_one_3

The transfer and the account is now updated as expected.

6.2.Bidirectional rule

In our example, we have only shown you how to send data from Prestashop to SuiteCRM. But in reality, Myddleware allows you to send data in both direction, from Prestashop to SuiteCRM and from SuiteCRM to Prestashop.

One of the rule we have created is sending Prestashop Customer to SuiteCRM contacts. In this case, only modification in Prestashop would be sent to SuiteCRM, But if the contact is modified in SuiteCRM, the modification won’t be sent to Prestashop.

So let’s create a new rule to send the modification of the SuiteCRM contact to Prestashop. Select the same modules and connectors you used in your previous rule but in the opposite direction :

rule_bidirectional_1

Go to fields mapping and map at least fields fistname, lastname and email. Make sure you don’t use a field that will be updated everytime like the modification date of the record, you can create an infinite while we show you how to check if your bidirectional rule is correct.

Then go to validation, a new filed is displayed “Bidirectional synchronization” with the opposite rules. Select the opposite rule and click on “Confirm” :

rule_bidirectional_2

The opposite rule is displayed on the detail view rule :

rule_bidirectional_3

Activate both rules. Now, to test your bidirectional rule, modify a customer in Prestashop, go to the list rule view and click on “Execute all active rules” :

rule_bidirectional_4

Now open the task and you will see the contact has been sent to SuiteCRM

rule_bidirectional_5

So in SuiteCRM, the contact’s name was “Doe test” and we sent “Doe”.  The name is now modified in SuiteCRM. Return now to the list rule view and click again on “Execute all active rules”. Another transfer is sent as a result of Myddleware reading in SuiteCRM and detecting the modification we’ve just made. The transfer has to be automatically cancelled to avoid infinite while:

rule_bidirectional_6

This is because the data is already updated in Prestashop (normal, it is Prestashop which sent it to SuiteCRM), Myddleware detect no modification to send to Prestashop so Myddleware cancel the transfer and stop the while.

Now you have to do this test in the opposite direction. To do so, modify the contact in SuiteCRM and return to the list rule view and click again on “Execute all active rules”. You should have only run the rules once, not 2 times as previously. In fact it depends which rule is sent first when you click on “Execute all active rules”. In one direction, you have to click run all rules 2 times, in the other direction once  is enough.

At this point, your modification in SuiteCRM should have been sent to Prestashop :

rule_bidirectional_7

Then Myddleware will detect the modification in Prestashop and will try to send it to SuiteCRM, but once again, the transfer would be cancelled to stop the while :

rule_bidirectional_8

If the transfer isn’t cancelled, your server will continue to update the same contacts every time. To avoid this, you will have to detect why the transfer isn’t cancelled, it could be because you use the modification date, or because the data format is not the same between your 2 applications. To solve this problem, remove fields in your rule or create a formula to have the same data in both applications.

Suggest Edit