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 e 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 no que se refere ao Harmony Design Studio e seu conector SAP.
Terminologia SAP¶
- SAP: Quando nos referimos a SAP, queremos dizer uma versão do SAP 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 no local.
- 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 trocar dados entre sistemas SAP, os IDocs também podem ser usados para integração de externo. Esteja ciente de que um IDoc usa abreviações em alemão 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 de SOAP ou REST é que um BAPI tem um único método e é específico para um objeto. Por exemplo, existem 60 BAPIs relacionados exclusivamente ao objeto cliente da SAP. Os BAPIs são entregues e mantidos pela SAP.
- RFC: Um RFC (Remote Function Call) é o mesmo que um BAPI, exceto que um RFC pode ou não ser mantido em atualizações SAP. Alguns RFCs são padrão e fornecidos 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 Conector SAP do Harmony Design Studio usa Conector SAP Java (SAP JCo) para trabalhar com objetos SAP e é compatível com ECC versão 6 ou posterior e SAP S/4HANA no local. O Conector SAP pode ser usado pronto para uso para comunicações de entrada SAP de Harmony para SAP usando RFCs, BAPIs ou IDocs.
- Ouvinte de evento 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 Conector SAP ouvindo e recebendo IDocs de saída SAP. Usando o protocolo RFC transacional (tRFC), os IDocs são enviados em lote sem uma ordem definida. Usando o protocolo RFC enfileirado (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 utilizada no projeto de integração:
- Uma atualização bem-sucedida geralmente tem IDs de registro na resposta, que podem ser usados para atualizar o aplicativo de origem.
- Se um erro for retornado, ele pode 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, a ação do usuário será necessária para reprocessar o IDoc.
Há certos cenários em que um IDoc é preferível:
- Um IDoc pode conter vários registros, enquanto BAPIs e RFCs geralmente podem manipular 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 funcionalidade que um IDoc pode invocar que não esteja disponível usando um BAPI ou RFC.
Estrutura IDoc¶
A estrutura de um IDoc é plana. Embora o XML pareça hierárquico, os nós repetidos não estã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 o SAP possa exibir datas em sua GUI em diferentes formatos (seguindo as convenções do país), o formato de dados para as APIs do 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 um SoldTo e um BillTo, com um cliente diferente como ShipTo.
- Um cliente pode ser um SoldTo com muitos outros clientes sendo ShipTos (um caso comum em que um cliente de franquia tem muitos locais)
Ao usar o objeto de cliente SAP em projetos de integração, é essencial ter uma compreensão completa dos requisitos de integração para clientes e funções de parceiro.
Com um carregamento inicial de dados, em geral os clientes SoldTo precisam ser carregados primeiro, pois os outros clientes dependem da existência de SoldTo no endpoint para construir o relacionamento. Como o BillTo contém o endereço de cobrança, frequentemente a definição do cliente 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 terminal de endpoint sejam refletidas nas funções de clientes e 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 em outros endpoints, isso requer um trabalho personalizado no endpoint e no próprio SAP para lidar com as funções do parceiro. Este exemplo mostra como mover contas do Salesforce para SAP e lida com o gerenciamento da função de parceiro:
Capturando Dados Alterados para Objetos de Dados Mestre¶
Em geral, os 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 usando 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 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 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 vez, o SAP Event Listener instanciará vários encadeamentos e criará várias chamadas simultâneas. Se a chamada for para atualizar um endpoint com limites de login, como 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 Armazenar e Encaminhar¶
A alternativa ao processamento direto é o processamento de armazenamento e encaminhamento, no qual 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 está em um cronograma rápido (como a cada minuto) e verifica o diretório de arquivos em busca de arquivos para processar. Quando os arquivos são encontrados, os arquivos são repetidos 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é esgotar. Se houver falha técnica durante o processo, o arquivo não é deletado e é reprocessado uma segunda vez.
Nota
Por padrão, os arquivos temporários são armazenados por 24 horas antes de serem excluídos. Isso é 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 agendamento pode selecionar Agente 2, que não encontrará arquivos para processar. Não será até que o Agente 1 seja 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é serem esgotados. 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 de falha adicional. Os clusters de Agente são usados para failover e balanceamento de cargas, portanto, o uso de armazenamentos de dados externos que não são configurados de maneira semelhante pode minar a robustez geral do sistema.
Extraindo um ID para Buscar Dados Adicionais¶
Se o IDoc tiver um ID, um BAPI pode ser chamado 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 é usado para chamar um RFC personalizado. Esta captura de tela mostra a transformação extraindo o ID do material:
Como Tutoriais Específicos do SAP¶
Esta seção fornece tutoriais específicas da SAP para estes tópicos:
Lidando com Datas de Término Vazias¶
Se uma data final 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().
Encontrar Funções de Clientes e Parceiros¶
Ao procurar a função adequada de cliente ou parceiro no SAP, preste atenção especial às abreviações em alemão.
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 do SAP usa a abreviação alemã AG conforme mostrado na primeira coluna:
| Função de parceiro | Idioma | Nome | Função de parceiro específica de idioma |
|---|---|---|---|
| AG | PT | Parte da ordem de venda | SP |
| RE | PT | Bill-To Party | PA |
| RG | PT | Pagador | PY |
| NÓS | PT | Ship-To Party | 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.
Manipulando Convenções BAPI¶
Certos BAPIs - como BAPI_SALESORDER_CREATEFROMDAT2— possuem conjuntos de campos que requerem tratamento especial.
Conforme mostrado abaixo, os campos que são mapeados no cabeçalho (ORDER_HEADER_IN) se repetem 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 sob ORDER_ITEMS_INX não tem "X" inserido; em vez disso, ele recebe o mesmo número de item usado no campo ORDER_ITEMS_IN:
Tratamento de Funções de Parceiro com Pastas Adicionais¶
Nesta seção, precisamos passar SoldTo, ShipTo e BillTo. Adicionamos pastas adicionais para mapeá-las e padronizamos as funções de parceiro (AG, WE, RE):
Lidando com as Funções do Parceiro com o SetInstances Função¶
Uma alternativa para adicionar novas pastas é usar o SetInstances() função sem pastas adicionais:
Na condição raiz, criaríamos uma série de arrays dentro de um PartnersArray e defini-lo 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().
Manipulando Números de Linha de Incremento¶
Na seção ORDER_SCHEDULES_IN, mais uma vez inseriríamos 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 sob 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$);
Solucionando Problemas de Confirmações BAPI¶
Em alguns cenários, você pode descobrir que, embora a execução de um BAPI pareça ser bem-sucedida, a transação esperada não é confirmada no SAP.
Isso pode ocorrer se um BAPI retornar um tipo de resposta diferente de S(Sucesso). O Conector SAP do Jitterbit, por padrão, emite uma confirmação de transação BAPI (no mesmo encadeamento) 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 um BAPI personalizado, recomendamos alterar o BAPI para retornar um Success.