Criar etapas de trabalho personalizadas

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

• Listar as etapas necessárias para criar um trabalho personalizado.
  
• Descrever a diferença entre um módulo de script orientado a tarefas e um orientado a partes.
  
• Explicar o que é o arquivo steptypes.json.
  

Introdução

Linda Rosenberg, administradora da Cloud Kicks, está criando um trabalho e não consegue encontrar uma etapa do sistema que faça exatamente o que ela quer. Ela quer importar dados diretamente de um sistema de informações externas sobre produtos (PIM) para a instância de produção. Ela precisa de código personalizado para fazer isso porque quer importar os dados do catálogo, processá-los e salvá-los no banco de dados do Salesforce B2C Commerce. Não é apenas uma simples importação. Para criar esse trabalho personalizado, ela pede a um desenvolvedor da Cloud Kicks, Vijay Lahiri, para fazer essas etapas.

1. Criar um cartridge. Um cartridge é um mecanismo para empacotar e implantar código e dados do programa de loja do B2C Commerce.
   
2. Escrever um script orientado a tarefas ou orientado a partes para executar as etapas do processo, por exemplo, para ler um registro de produto, processá-lo e, em seguida, escrevê-lo no banco de dados.
   
3. Criar um arquivo steptypes.json para descrever as etapas personalizadas e colocar o arquivo na raiz do cartridge.
   
4. Carregar o cartridge e o incluir no caminho de acesso do cartridge.
   

Vijay está feliz em ajudar.

Quando ele terminar, Linda:

1. Replica o código para produção e ativa a versão de código que inclui o novo cartridge.
   
2. Cria um trabalho usando a etapa personalizada no Business Manager.
   

Módulo de script orientado a tarefas

Agora as coisas vão ficar um pouco técnicas, mas Linda precisa entender os seguintes conceitos e processos focados no desenvolvedor para que ela possa colaborar com Vijay, monitorar o sucesso do trabalho e planejar requisitos futuros.

Um módulo de script CommonJS orientado a tarefas expõe uma função a ser chamada como a função principal para a etapa de trabalho. Quando Linda cria trabalhos usando o Business Manager, ela define parâmetros disponibilizados como objetos que podem ser usados com script para a função do módulo e para o objeto dw.job.JobStepExecution. O objeto dw.job.JobStepExecution permite acesso somente de leitura a informações sobre a execução da etapa atual e execução do trabalho.

Para controlar o status de saída, a função pode retornar um objeto de API dw.system.Status. Se o script terminar com uma exceção não tratada, o código de status de saída será ERROR e o sinalizador de status de erro será true por padrão. Se nenhum objeto de status for retornado e nenhuma exceção ocorrer, o código de status será OK por padrão.

Consulte o Infocenter para obter um exemplo de um módulo de script orientado a tarefas que se conecta via FTP e, em seguida, baixa dados. Vijay usa esse exemplo para criar o módulo de script.

Módulo de script orientado a partes

Um módulo de script CommonJS orientado a partes lê e processa itens em partes de um tamanho especificado. Se a lista contiver mais itens do que o B2C Commerce pode processar em uma parte, ele inicia uma nova parte. Um script orientado a partes pode incluir qualquer série de etapas de processamento, não apenas transações de banco de dados.

Uma etapa de trabalho que usa um script orientado a partes permite o monitoramento otimizado do progresso porque o B2C Commerce atualiza o número de elementos que são escritos cada vez que uma parte é concluída.

Vijay e Linda dão uma olhada em um exemplo de processamento de partes.

Suponha que você exporte uma lista de oito pedidos para um arquivo, e o tamanho de uma parte é de quatro pedidos. O script processa as partes conforme a sequência a seguir.

1. Ler pedido 1, Processar pedido 1, Ler pedido 2, Processar pedido 2, Ler pedido 3, Processar pedido 3, Ler pedido 4, Processar pedido 4
   
2. Escrever pedido 1, Escrever pedido 2, Escrever pedido 3, Escrever pedido 4
   
3. Ler pedido 5, Processar pedido 5, Ler pedido 6, Processar pedido 6, Ler pedido 7, Processar pedido 7, Ler pedido 8, Processar pedido 8
   
4. Escrever pedido 5, Escrever pedido 6, Escrever pedido 7, Escrever pedido 8
   

Funções do script em partes

Linda notou três funções no exemplo. Um módulo de script orientado a partes expõe funções para leitura, processamento e gravação.

• função de leitura: retorna um item ou nada.
  
• função de processamento: permite transformar itens e aplicar a lógica de negócios a eles.
  
• função de gravação: recebe uma lista de itens.
  

Você também pode usar essas funções opcionais em um módulo de script orientado a partes.

• função de contagem total: retorna o número total de itens disponíveis antes do início do processamento em partes.
  
• função antes da etapa: executada antes que uma etapa da parte comece.
  
• função antes da parte: executada antes que uma parte comece.
  
• função após a parte: executada depois que uma parte termina.
  
• função após a etapa: executada após uma etapa da parte ser concluída com sucesso.
  

Consulte o Infocenter para obter um exemplo de um módulo de script orientado a partes.

Arquivo steptypes

Quando Vijay cria uma etapa personalizada, ele deve criar um arquivo steptypes.json para descrever os metadados da etapa. Este arquivo especifica o módulo de script que implementa a etapa, os parâmetros que a etapa requer e os status de saída que a etapa retorna. O arquivo steptypes.json requer uma sintaxe muito específica. Por exemplo, uma parte do arquivo steptypes.json usa os seguintes pares de nome/valor:

"@name":"MyParameter1",
"@type":"boolean",
"@required":"true",
"description":"A required boolean parameter."

Consulte o Infocenter para obter detalhes sobre a sintaxe e um exemplo de um arquivo steptypes.json.

Solução de problemas de arquivos steptypes.json inválidos

O B2C Commerce analisa e carrega o arquivo steptypes.json:

• Na inicialização do servidor.
  
• Quando a versão de código ativa é alterada.
  
• Em sandboxes, cada vez que uma etapa é executada.
  

Se um arquivo steptypes.json contiver erros devido a atributos ausentes ou outros problemas, o B2C Commerce registra os erros em um arquivo de erros e não registra a etapa personalizada. O B2C Commerce então carrega as etapas dos arquivos steptypes.json de outros cartridges.

Os arquivos steptypes.json inválidos fazem com que mensagens como esta apareçam no Business Manager:

Invalid step [Step1]! Type with id [custom.MyCustomStep1] is unknown!

Se Linda importar trabalhos inválidos, ela recebe um aviso no registro de importação/exportação e uma mensagem de erro no Business Manager. Se Vijay alterar o arquivo steptypes.json de modo que ele crie um trabalho inválido, ele não executa mais, e nada acontece, exceto uma entrada no registro do trabalho.

Usar o arquivo steptypes.xml

Vijay pode usar uma definição XML em vez de JSON para definir as etapas personalizadas. Ele deve chamar o arquivo steptypes.xml e colocá-lo em um cartridge personalizado na pasta raiz. O B2C Commerce analisa e recarrega o arquivo sempre que a versão de código ativa é alterada. Pode haver apenas um arquivo steptypes.json ou steptypes.xml.

Próximas etapas

Neste módulo, Linda aprendeu a criar uma etapa de trabalho personalizada com a ajuda de Vijay, um desenvolvedor da Cloud Kicks. Em seguida, ela vai aprender a criar e configurar trabalhos.

Recursos

• Trailhead: Criar seu site de comércio eletrônico com o Salesforce B2C Commerce
• Ajuda: Módulo de script orientado a tarefas
• Ajuda: Módulo de script orientado a partes
• Ajuda: Criar etapas de trabalho personalizadas