TOTVS RM as a destination

​

What you need in RM

1. The RM REST server published over HTTPS and reachable from the internet, with the firewall open to Nekt’s IP addresses. It is the address of RM.Host, usually on port 8051, for example https://rm.yourcompany.com.br:8051. RM answers plain HTTP on that port by default: TOTVS documents how to turn on HTTPS as “Habilitar SSL/TLS no Host”.
2. An RM user dedicated to this integration, not used by people. Orders typed in RM with this login and without an IDINTEGRACAO make the connector stop writing (see Avoiding duplicates). In Serviços Globais > Segurança > Perfis, its profile needs:
   • the item Integração com WebService do Movimento (MovMovimentoTBCData) in Acesso a Menus;
   • permission to consult and include the movement type used for the orders. The connector reads the orders back to check whether they already exist, so permission to include alone is not enough;
   • optionally, Desconsiderar Filtro de Produto em WebService for the company. Without it, RM’s data protection filter can hide customers from the user, and the dry run reports them as not found.
3. The movement type of the sales order (for example 2.1.01), already configured in RM: its series and numbering (in the movement type’s parameters, Mov. Identificação > Série, and in Definições Gerais > Numeração de movimento). When the numbering is automatic, RM numbers each order; otherwise send the number in the NUMEROMOV column. Fields the movement type makes mandatory must be sent too (see Fixed values below).

​

1. Add your TOTVS RM access

1. In the Destinations tab, click on the “Add destination” button located on the top right of your screen. Then, select the TOTVS RM option from the list of connectors.
2. Click Next and you’ll be prompted to add your access:
   • RM server URL: the HTTPS address of your RM REST server, with the port, for example https://rm.yourcompany.com.br:8051.
   • Username and Password: the RM user for the integration.
   • Company (coligada) code: the RM company (CODCOLIGADA) where the orders are created, for example 1.
   • Branch (filial) code: the branch (CODFILIAL) of the orders, for example 1.
   • Warehouse (local de estoque) code: the stock location (CODLOC) of the orders, for example 01.
   • Movement type code: the movement type (CODTMV) of your sales orders, for example 2.1.01.
   • Dry run: on by default. The connector signs in, checks every order against RM with read-only lookups, and shows the first orders it would send and a summary in the run log, without creating anything. Turn it off to create the orders.
   • Max orders created per run: the most orders created in one run; the others wait for the next runs. Leave it empty for no limit. Use 1 on the first real run, then raise it.
   • Enable partial success (advanced): what happens when RM refuses some orders. Off: the other orders are created and the run ends as failed, so the refusals are noticed. On: the run ends successfully and the refusals are listed in the run log.
   • Fixed values (advanced): RM columns sent with every order, written as a JSON object, for example {"SERIE": "1", "item.CODUND": "UN"}. Use it for values your movement type requires and your table does not have. A column of your table mapped to the same RM column takes precedence.
   • RM server timezone (advanced): the timezone of your RM server. Dates and times with a timezone are converted to it.
   • Verify SSL certificate (advanced): turn off only when the RM server uses a self-signed certificate.
   The branch, warehouse and movement type can also come from your table, per order, by mapping a column to CODFILIAL, CODLOC or CODTMV.
3. Click Next.

​

2. Select your data to send

1. The next step is letting us know which data you want to send. Select the layer and then the desired table.

   Tip: The table can be found more easily by typing its name.

2. Click Next.

​

How the table must look

SELECT p.id                AS pedido_id,    -- the order's id in your system
       p.codigo_cliente_rm AS cliente,      -- customer code in RM (CODCFO)
       p.data              AS data_pedido,  -- order date
       p.condicao_rm       AS condicao,     -- payment terms code in RM (CODCPG)
       i.idprd_rm          AS produto_id,   -- product id in RM (IDPRD)
       i.quantidade,
       i.preco_unitario,
       i.unidade                            -- unit code in RM, e.g. UN
FROM pedidos p
JOIN itens_pedido i ON i.pedido_id = p.id
WHERE p.status = 'pronto_para_integrar'

• The product is identified by RM’s internal product id (IDPRD). If you also use the TOTVS RM source, you can find it by joining with its products table.
• Numbers use a dot as the decimal separator. Quantities can have up to 4 decimal places and unit prices up to 10; an order with more is refused, so round them in your Query. Dates can be dates or date-times.
• Discounts (VALORDESC, PERCENTUALDESC) are not supported yet and are refused; they will come in a future version.
• Columns of the order must have the same value on every row of the order; an order whose rows disagree is refused. An empty cell on some rows is fine.

​

3. Map your columns

​

Transforms

​

4. Configure your TOTVS RM data destination

1. Describe your destination for easy identification within your organization. You can inform things like what data it brings, to which team it belongs, etc.
2. To define your Trigger, consider how frequently you need to have the data updated on the destination (every day, once a week, only at specific times, etc.).
3. Click Done.

​

Check your new destination!

1. Once completed, you’ll receive confirmation that your new destination is set up!
2. You can view your new destination on the Destinations page. Since Dry run is on, the first run creates nothing: open its run log to see the result.

​

What the run log shows

• checks that the RM user can read movements of the movement type;
• looks up every order id in RM, to find orders that already exist;
• looks up every customer, product, warehouse and unit used, and whether they are active;
• shows the first three orders exactly as they would be sent (CPF and CNPJ numbers are partially hidden);
• ends with a summary: how many orders would be created, how many already exist and how many would be refused, with the reason for each refused order.

​

First real run

1. Keep Dry run on and run the destination. Read the orders shown in the run log and the summary.
2. Turn Dry run off and set Max orders created per run to 1. Run the destination and open the new movement in RM: check the customer, the items, the values and that the IDINTEGRACAO column holds your order id.
3. When it looks right, raise the limit (for example to 10), and later clear it.

​

Avoiding duplicates

• It saves each order’s id in the movement’s IDINTEGRACAO column and looks every id up in RM before sending, and once more right before sending each order. An order found with the same id and the same customer is skipped and listed in the run log with its RM movement id.
• If the id is already used in RM by a movement of another customer, or differs only in upper/lower case from an id in RM, the order is not created and the run log says why.
• An order is sent again only when RM clearly refused to process it (for example, the server was busy). If RM does not answer clearly (a timeout or a dropped connection), the connector does not send it again and sends no other order in that run, which then fails with a message. Check the order in RM; the next run looks it up before sending anything.
• After creating the first order of each movement type in a run, it reads the order back from RM and checks that the items and the order id were saved. If not, it stops and asks you to pause the pipeline.
• Before sending anything, it checks whether RM has movements that could be orders sent earlier by the connector whose id RM did not keep: same customer and movement type as an order to send, an empty IDINTEGRACAO, issued in the last 30 days or later (or on the date of an older order being sent), and at least one product in common; or any movement of that type created by the integration’s RM user with an empty IDINTEGRACAO. If it finds any, the run sends nothing and fails, listing their movement ids. It also stops when there are too many such movements to check in one run. In a dry run these are warnings.
• If RM answers that it is busy, the connector looks the order up again before sending it a second time. If an order id is ever found twice for the same customer and movement type, the run stops with a possible duplicate alert. Check the movements listed; if one is a duplicate, change its IDINTEGRACAO or delete it (cancelling it is not enough, it keeps the order id), then run again.

​

When a run stops because of movements without an order id

• if it is an order sent by this connector, fill its IDINTEGRACAO with that order’s id: the next run treats it as already created;
• if it is not (for example, an order typed by hand for that customer), fill its IDINTEGRACAO with any value that is not an order id of your table.

• Do not run the destination twice at the same time. Keep the interval between scheduled runs longer than a run takes; two runs sending the same order at the same moment could both create it.
• If RM does not keep the order id, an order more than 30 days old whose date you change in your table to another old date is not caught by the check above.
• An order that already exists in RM is skipped as a whole: items added to your table later are not added to it.
• The read-back covers the first order of each movement type in a run, not every order.
• The check above is broad on purpose: orders typed by hand in RM for the same customers and products, without an IDINTEGRACAO, stop the runs until their IDINTEGRACAO is filled.
• In rare cases (an RM that does not keep the order id combined with an order whose products all changed, or a busy answer while RM was still saving), one duplicate can still be created. The connector then stops with an alert in that run and in every later one until it is resolved.

If you encounter any issues, reach out to us via Slack, and we’ll gladly assist you!