Melhores Práticas para SAP¶
Introdução¶
Há uma série de questões e considerações exclusivas para projetos de integração SAP, especialmente para integrações bidirecionais. Esta página apresenta informações relevantes para todas as integrações SAP, padrões de integração comuns para SAP e suas considerações de design, além de tutoriais específicas do SAP.
Informação Básica¶
Esta seção aborda a terminologia SAP e Jitterbit, atualizando dados SAP, a estrutura IDoc e formatos de data.
Terminologia¶
Esta seção define a terminologia específica do SAP relacionada ao Harmony Design Studio e seu conector SAP.
Terminologia SAP¶
- SAP: Quando nos referimos a SAP, queremos dizer uma versão do SAP que é compatível com o Harmony Design Studio SAP Connector. O componente essencial que o Design Studio SAP Connector requer é uma versão do SAP que usa o SAP Java Connector (SAP JCo). Isso inclui ECC versão 6 ou posterior e SAP S/4HANA de locatário único.
- IDoc: Um Documento Intermediário (IDoc) é um arquivo de texto com um formato predefinido semelhante a um documento de Intercâmbio Eletrônico de Dados (EDI). Existem IDocs para objetos de dados mestre, como clientes e fornecedores, bem como para objetos transacionais, como pedidos de vendas. Originalmente usados para troca de dados entre sistemas SAP, os IDocs também podem ser usados para integração de externo. Esteja ciente de que um IDoc utiliza abreviaturas alemãs dentro do documento.
- BAPI: Uma Business Application Programming Interface (BAPI) é uma API — semelhante a uma API SOAP ou REST — e usa uma construção de solicitação e resposta para se comunicar com o SAP. Uma diferença principal do SOAP ou REST é que uma BAPI possui um único método e é específica para um objeto. Por exemplo, existem 60 BAPIs relacionadas exclusivamente ao objeto cliente da SAP. BAPIs são entregues e mantidos pela SAP.
- RFC: Uma RFC (Chamada de Função Remota) é igual a uma BAPI, exceto que uma RFC pode ou não ser mantida em atualizações SAP. Algumas RFCs são padrão e fornecidas pela SAP. RFCs personalizados também podem ser criados para dar suporte a integrações e devem ser mantidos pelo cliente SAP.
Terminologia Jitterbit¶
- Conector SAP: O Harmony Design Studio SAP Connector usa SAP Java Connector (SAP JCo) para trabalhar com objetos SAP e é compatível com ECC versão 6 ou posterior e SAP S/4HANA local. O SAP Connector pode ser usado imediatamente para comunicações de entrada SAP do Harmony para SAP usando RFCs, BAPIs ou IDocs.
- Ouvinte de eventos SAP: O Jitterbit SAP Event Listener é um aplicativo que é instalado e executado como um serviço em um servidor Windows ou Linux. Ele estende a funcionalidade do SAP Connector ouvindo e recebendo IDocs de saída SAP. Utilizando o protocolo RFC transacional (tRFC), os IDocs são enviados em lote sem ordem definida. Usando o protocolo RFC em fila (qRFC), o SAP Event Listener responde ao SAP após receber cada IDoc, sinalizando ao SAP para enviar o próximo IDoc na transação.
Atualizando Dados SAP¶
Como prática recomendada, ao atualizar dados no SAP, geralmente é preferível usar um BAPI ou RFC em vez de um IDoc. A principal razão para isso é que BAPIs e RFCs retornam uma resposta que pode ser usada no projeto de integração:
- Uma atualização bem-sucedida geralmente possui IDs de registro na resposta, que podem ser usados para atualizar o aplicativo de origem.
- Se um erro for retornado, ele poderá ser incorporado aos processos de tratamento de erros.
Em comparação, quando um IDoc é enviado, a única confirmação enviada de volta é um código indicando que foi recebido; não há indicação de sucesso ou fracasso. Os IDocs são processados no SAP de forma assíncrona. Se um IDoc falhar, será necessária uma ação do usuário para reprocessar o IDoc.
Existem determinados cenários em que um IDoc é preferível:
- Um IDoc pode conter vários registros, enquanto BAPIs e RFCs geralmente podem lidar com apenas uma única atualização de registro. Um cenário de atualização em massa pode exigir o uso de um IDoc.
- Um IDoc pode ser usado para capturar dados alterados, enquanto BAPIs e RFCs não podem lidar com consultas baseadas em carimbo de data/hora.
- Pode haver funcionalidades que um IDoc pode invocar e que não estão disponíveis usando BAPI ou RFC.
Estrutura do IDoc¶
A estrutura de um IDoc é plana. Embora o XML pareça hierárquico, os nós repetidos não são realmente aninhados nos nós pais.
Na estrutura de exemplo abaixo, todos os segmentos do pai IDOC estão no mesmo subnível. As informações do cabeçalho estão no mesmo nível das informações do item:
Formatos de Data¶
Embora a SAP possa exibir datas em sua GUI em diferentes formatos (seguindo as convenções do país), o formato de dados para as APIs SAP é yyyy-mm-dd.
Padrões de Integração¶
Esta seção apresenta padrões de integração comuns que podem ser usados para interagir com dados SAP.
Integração de Dados Mestres de Clientes¶
No SAP, um cliente pode ser uma das — ou uma combinação de — funções de parceiro, como SoldTo, ShipTo e BillTo. Por exemplo:
- Um cliente pode ser seu próprio SoldTo, ShipTo e BillTo.
- Um cliente pode ser SoldTo e BillTo, com um cliente diferente como ShipTo.
- Um cliente pode ser um SoldTo com muitos outros clientes sendo os ShipTos (um caso comum onde um cliente de franquia tem muitos locais)
Ao usar o objeto cliente SAP em projetos de integração, é essencial ter um entendimento completo dos requisitos de integração tanto para os clientes quanto para as funções do parceiro.
Com um carregamento inicial de dados, em geral os clientes SoldTo precisam ser carregados primeiro, uma vez que os outros clientes dependem da existência de SoldTo no endpoint de destino para construir o relacionamento. Como BillTo contém o endereço de cobrança, frequentemente a definição do cliente do endpoint precisa dos endereços principal e de envio, e a integração precisa atualizar o cliente SoldTo com o endereço BillTo no endpoint.
No exemplo abaixo, um único IDoc do SAP resulta em um upsert para uma conta e uma conta filha de objeto personalizado no Salesforce:
Integrações Bidirecionais¶
Projetos de integração bidirecional são aqueles em que os dados fluem de e para cada endpoint. Por exemplo, você pode precisar que os dados do cliente SAP sejam criados em um endpoint de destino e que quaisquer alterações nos dados do cliente nesse endpoint de destino sejam refletidas em clientes e funções de parceiros no SAP.
Como as regras de validação de dados de criação de objetos do SAP são mais rígidas do que outros endpoints, isso requer um trabalho personalizado tanto no endpoint quanto no próprio SAP para lidar com as funções do parceiro. Este exemplo mostra a mudança de contas do Salesforce para SAP e trata do gerenciamento da função do parceiro:
Capturando Dados Alterados para Objetos de Dados Mestre¶
Em geral, IDocs são usados para capturar dados alterados no SAP, pois BAPIs e RFCs não podem lidar com consultas baseadas em carimbo de data/hora.
Os IDocs podem ser configurados para serem gerados utilizando ponteiros de alteração associados a um objeto e podem ser gerados para conter todos os dados ou apenas as alterações. Obter todos os dados geralmente é uma escolha melhor, pois pode haver relacionamentos nos dados que são necessários para um upsert. No entanto, atualizações em massa de dados podem acionar milhares de IDocs por vez, cujo processamento pode exceder o login ou outros limites no endpoint de destino.
Processamento Direto¶
O processamento direto segue este fluxo de dados:
- O SAP Event Listener recebe um IDoc.
- O SAP Event Listener move a payload para a fila de operação Jitterbit.
- A operação recebe o IDoc.
- Os dados do IDoc são carregados no endpoint de destino.
Embora o processamento seja direto, considere estes efeitos do processamento direto:
- Se milhares de IDocs forem enviados de uma só vez, o SAP Event Listener instanciará vários threads e criará diversas chamadas simultâneas. Se a chamada for para atualizar um endpoint com limites de login, como o Salesforce, o volume de chamadas poderá exceder os limites de login.
- Se o endpoint de destino estiver inacessível, a payload do IDoc não será entregue ao destino final e será perdida.
Processamento de Armazenamento e Encaminhamento¶
A alternativa ao processamento direto é o processamento store-and-forward, em que a payload do IDoc é gravada em um arquivo temporário.
No exemplo de cadeia de operação abaixo:
-
A primeira operação recebe um IDoc do SAP Event Listener e o armazena localmente.
-
A segunda operação ocorre em uma programação rápida (como a cada minuto) e verifica o diretório de arquivos em busca de arquivos para processamento. Quando os arquivos são encontrados, eles passam por um loop e cada arquivo é passado para a próxima operação.
-
Quando a última operação da cadeia é executada, ela exclui o arquivo e o loop é repetido até se esgotar. Caso ocorra alguma falha técnica durante o processo, o arquivo não é excluído e é reprocessado uma segunda vez.
Nota
Por padrão, os arquivos temporários são armazenados por 24 horas antes de serem excluídos. Isto é configurável por um período mais longo, se necessário.
Ao executar operações em um ambiente multiagente, um IDoc pode ser recebido pelo Agente 1 e armazenado localmente, mas o planejamento pode selecionar o Agente 2, que não encontrará arquivos para processar. Somente quando Agente 1 for chamado pelo agendador é que seus arquivos serão processados.
Lembre-se de que todos os arquivos nos diretórios temporários serão processados até se esgotarem. Se houver um requisito de que os IDocs sejam processados em ordem, use um recurso compartilhado, como um site FTP, um sistema de arquivos local ou um banco de dados. No entanto, adicionar armazenamentos de dados externos pode criar um ponto adicional de falha. Os clusters de Agente são usados para failover e balanceamento de cargas, portanto, o uso de armazenamentos de dados externos que não sejam configurados de forma semelhante pode prejudicar a robustez geral do sistema.
Extraindo um ID para Buscar Dados Adicionais¶
Se o IDoc tiver um ID, uma BAPI poderá ser chamada para buscar dados adicionais:
No exemplo acima, observando a terceira operação (3. Mat-Get Details), o IDoc é lido para recuperar o ID do material, que é então usado para chamar um RFC customizado. Esta captura de tela mostra a transformação extraindo o ID do material:
Tutoriais Específicas do SAP¶
Esta seção fornece tutoriais específicas do SAP para estes tópicos:
Lidando com Datas de Término Vazias¶
Se uma data de término não for preenchida no SAP (como pode ser o caso de um contrato "evergreen"), a SAP enviará 00000000 em um IDoc, que pode ser capturado e manipulado:
result = FindValue("108", OUTPUT$ORDERS05.IDOC$E1EDP01.E1EDP03#.IDDAT$, OUTPUT$ORDERS05.IDOC$E1EDP01.E1EDP03#.DATUM$);
If(result == "00000000",
RunScript("<TAG>Scripts/WTOL</TAG>", "No End Date, using 12/31/4000");
result="40001231"
);
GetUTCFormattedDateTime(result, "UTC", false);
// The year 4000 is the maximum date used by Salesforce
Para mais detalhes, consulte as funções Jitterbit FindValue(), RunScript(), e GetUTCFormattedDateTime().
Encontrando Funções de Clientes e Parceiros¶
Ao procurar a função apropriada de cliente ou parceiro no SAP, preste atenção especial às abreviações alemãs.
Por exemplo, ao criar um pedido de venda, no SAP GUI você pode ver um nome como Sold-To Party ou a função de parceiro equivalente específica do idioma SP, mas a API SAP usa a abreviatura alemã AG conforme mostrado na primeira coluna:
| Função de Parceiro | Idioma | Nome | Função de Parceiro Específica do Idioma |
|---|---|---|---|
| AG | PT | Parte Vendida | SP |
| RE | PT | Festa de cobrança | PA |
| RG | PT | Pagador | PA |
| NÓS | PT | Festa de envio | SH |
Usando o SAP Function Builder para Modelar uma Chamada de API¶
Ao mapear dados em uma transformação usando um destino BAPI ou RFC, é útil testar os valores exatos que o SAP está procurando, pois o que é visto na GUI do SAP geralmente não é o que é usado na API do SAP.
Você pode usar o código de transação SAP SE37 para acessar o Function Builder do SAP para modelar uma chamada BAPI ou RFC. Para obter um exemplo completo, consulte Parte 2: Modelando a consulta na instância SAP em Guia para usar RFC_READ_TABLE para consultar tabelas SAP.
Tratamento de Convenções BAPI¶
Certos BAPIs - como BAPI_SALESORDER_CREATEFROMDAT2 — possuem conjuntos de campos que requerem tratamento especial.
Conforme mostrado abaixo, os campos mapeados no cabeçalho (ORDER_HEADER_IN) são repetidos no *_INX pasta. Para informar ao SAP que você pretende preencher os campos de cabeçalho, insira um "X" como o valor do campo em cada um dos campos que são uma repetição de um campo de cabeçalho:
No entanto, no ORDER_ITEMS_INX seção, o ITM_NUMBER campo abaixo ORDER_ITEMS_INX não tem um "X" inserido; em vez disso, ele recebe o mesmo número de item usado no campo ORDER_ITEMS_IN:
Lidando com Funções de Parceiro com Pastas Adicionais¶
Nesta seção, precisamos passar SoldTo, ShipTo e BillTo. Adicionamos pastas adicionais para mapeá-los e padronizamos as funções dos parceiros (AG, WE, RE):
Lidando com Funções de Parceiro com o SetInstances Função¶
Uma alternativa para adicionar novas pastas é usar o SetInstances() funcionar sem pastas adicionais:
Na condição raiz, criaríamos uma série de arrays dentro de um PartnersArray e configure-o para o ORDER_PARTNERS usando:
SoldToParentArray = Array();
Set(SoldToParentArray, "AG", -1);
Set(SoldToParentArray, Order$Header$Sold_To_Customer_Number$, -1);
ShipToParentArray = Array();
Set(ShipToParentArray, "WE", -1);
Set(ShipToParentArray, Order$Lines$Line#1.Customer_Number$, -1); // new change
BillToParentArray = Array();
Set(BillToParentArray, "RE", -1);
Set(BillToParentArray, Order$Header$Bill_To_Customer_Number$, -1);
PartnersArray = Array();
Set(PartnersArray, SoldToParentArray, -1);
Set(PartnersArray, ShipToParentArray, -1);
Set(PartnersArray, BillToParentArray, -1);
SetInstances("ORDER_PARTNERS", PartnersArray);
True
Na condição de pasta em ORDER_PARTNERS, para definir as instâncias que usaríamos:
$instanceReference = GetInstance();
True
Para mais detalhes, consulte as funções Jitterbit Set(), GetInstance(), e SetInstances().
Tratamento de Números de Linha Incrementais¶
Na seção ORDER_SCHEDULES_IN, inseriríamos mais uma vez um "X" nos campos de dados.
Para o campo SCHED_LINE, o SAP os incrementa em 10 (linha 10, linha 20, linha 30 e assim por diante). Podemos usar um contador de variável global na condição abaixo ORDER_SCHEDULES_IN para calcular o valor:
If(Length($ItemLineCounterS) == 0, $ItemLineCounterS = 0);
$ItemLineCounterS = $ItemLineCounterS + 10;
True
Para mais detalhes, consulte a função Jitterbit Length().
Recuperando Valores de um IDoc¶
Aqui queremos obter as datas de início e término de um IDoc para criar um contrato. Os dados estão localizados aqui:
Em E1EDP03, queremos o DATUM valor onde IDDAT == 107 (ou 108) para as datas de início e término, respectivamente. Uma função útil para isso é o Jitterbit FindValue() função. Esta função percorrerá o IDDAT valores, encontre aquele com "107" e recuperar o DATUM campo:
result=FindValue("107", OUTPUT$ORDERS05.IDOC$E1EDP01.E1EDP03#.IDDAT$, OUTPUT$ORDERS05.IDOC$E1EDP01.E1EDP03#.DATUM$);
Solução de Problemas de Confirmações BAPI¶
Em alguns cenários, você poderá descobrir que, embora a execução de uma BAPI pareça ter sido bem-sucedida, a transação esperada não foi confirmada no SAP.
Isso pode ocorrer se uma BAPI retornar um tipo de resposta diferente de S (Sucesso). O conector SAP da Jitterbit, por padrão, emite um commit de transação BAPI (no mesmo thread) somente quando uma resposta BAPI é Success. No entanto, ele não emite uma confirmação de transação se a resposta BAPI for diferente de Success.
Por exemplo, o tipo de resposta pode ser I (Informação), E (Erro), ou W (Aviso). O tipo de resposta é retornado no RETURN campo TYPE do nó:
Se você estiver usando uma BAPI customizada, recomendamos alterar a BAPI para retornar um Sucesso.