Mapear datas de origem para campos Date do Salesforce e registrar erros de resposta no Jitterbit Studio

Introdução

Ao gravar dados no Salesforce a partir do Studio, dois padrões de scripts são consistentemente necessários nos mapeamentos de transformação:

• Formatação de campos de data: Os campos Date e DateTime do Salesforce exigem valores em formatos de string específicos. Quando os dados de origem contêm uma string de datetime (por exemplo, um timestamp de banco de dados no formato YYYY-MM-DD HH:MM:SS), o valor deve ser convertido para o formato que o Salesforce espera antes da operação de gravação ser executada.
• Registro de erros de resposta: As operações de gravação do Salesforce (como Upsert, Insert e Update) retornam um resultado por registro. Quando o processamento falha para um ou mais registros, o campo success na resposta é definido como false e um array de errors é preenchido com uma ou mais mensagens. Sem uma verificação explícita na transformação de resposta, essas falhas por registro podem passar despercebidas, mesmo quando a operação geral do Studio relata sucesso.

Este guia fornece ambos os scripts, explica cada componente e descreve onde posicioná-los.

Padrão de design

Ambos os scripts são posicionados em transformações dentro da mesma cadeia de operações de gravação do Salesforce. O script de conversão de data pertence à transformação de solicitação, que formata os dados de origem antes de enviá-los ao Salesforce. O script de registro de erros pertence à transformação de resposta, que mapeia a resposta da operação de gravação do Salesforce:

Este guia pressupõe que uma conexão Salesforce já esteja configurada no projeto.

Parte 1: Mapear uma data de origem para um campo Date do Salesforce

Os campos Date do Salesforce esperam valores no formato YYYY-MM-DD. Os campos DateTime do Salesforce esperam valores no formato ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). As funções GetUTCFormattedDate e GetUTCFormattedDateTime produzem esses formatos a partir de uma string de datetime de origem. Esta parte pressupõe que o campo de origem contém uma string de datetime no formato YYYY-MM-DD HH:MM:SS e que a hora de origem está em UTC.

Etapa 1: Abrir o editor de script do campo Date de destino

1. No Studio, abra a transformação em que o schema de destino vem de uma atividade de gravação do Salesforce (como Upsert, Insert ou Update).

2. No schema de destino, localize o campo Date ou DateTime a ser mapeado.

3. Clique no campo para abrir seu editor de script.

Etapa 2: Escrever o script de conversão de data

Para um campo Salesforce Date, use GetUTCFormattedDate, que retorna apenas a parte da data no formato YYYY-MM-DD:

// Source field must be in YYYY-MM-DD HH:MM:SS format, expressed in UTC.
// GetUTCFormattedDate returns YYYY-MM-DD, which is the required format for
// Salesforce Date fields.
// If the source date uses a different format, apply a conversion function
// before passing it to GetUTCFormattedDate. See the date and time functions
// reference for available options.
// The third argument (false) uses non-European (month-first) date format.
GetUTCFormattedDate(<source_field>, "UTC", false);

Para um campo Salesforce DateTime, use GetUTCFormattedDateTime em vez disso, que retorna a string de datetime ISO 8601 completa:

GetUTCFormattedDateTime(<source_field>, "UTC", false);

Substitua <source_field> pelo caminho para o campo de data de origem conforme aparece no schema de origem da transformação.

Parte 2: Registrar erros de uma resposta de operação Salesforce

As operações de gravação do Salesforce retornam uma resposta que inclui um array result. Cada elemento corresponde a um registro de entrada e contém:

• success: Um booleano que indica se aquele registro foi processado.
• errors: Um array de um ou mais objetos de erro, cada um com um campo message. Preenchido quando success é false.
• Um campo chave (como uma ID externa ou a ID do registro Salesforce).

Como result é um array, a transformação de resposta faz um loop sobre ele uma vez por registro de entrada. O script nesta parte verifica success em cada iteração e, quando é false, escreve uma entrada de log que identifica o registro que falhou pelo valor de seu campo chave.

Etapa 3: Adicionar uma transformação de resposta à operação

Se a atividade de gravação do Salesforce ainda não tiver uma transformação a jusante que mapeie a resposta:

1. Na tela de design, adicione uma etapa de Transformação após a atividade de gravação do Salesforce.

2. Abra a transformação. O esquema de resposta da atividade Salesforce aparece como a origem, incluindo o nó result (que faz um loop uma vez por registro de entrada), os campos success e errors dentro de result e o campo chave do lado de solicitação do esquema.

3. Para o esquema de destino, adicione um único campo String (por exemplo, response) ou use um esquema de destino existente se a resposta estiver sendo mapeada para um sistema a jusante.

Etapa 4: Escrever o script de registro de erros

Na transformação, clique no campo de destino para abrir seu editor de script. Escreva um script que verifica success para o registro de resultado atual e, quando é false, registra o valor do campo chave e as mensagens de erro:

// Check whether Salesforce processed this record successfully.
// If not, log the key field value and Salesforce error messages to the operation log.
// Update the field references below to match the paths in your response schema.
// If the key field changes in your Salesforce operation, update the FindByPos reference.
If(<result.success> == false,
    WriteToOperationLog("The following record failed to process. Record: " +
    FindByPos(SourceInstanceCount(), <request.records#.keyField>) +
    " The issue was: " +
    SumString(<result.errors#.message>, ". ", false)));

Substitua as referências de placeholder pelos caminhos de campo reais do esquema de origem da sua transformação:

Cada função no script tem um papel específico:

• A transformação faz um loop sobre o array result, então If avalia success uma vez por registro de entrada.
• WriteToOperationLog escreve os detalhes do erro no log de operação, onde ficam visíveis após a execução da operação.
• SourceInstanceCount retorna o índice baseado em 1 da iteração de loop atual. Como o array result e o array de registros de solicitação estão na mesma ordem, esse índice mapeia o resultado atual de volta para o registro de entrada correspondente.
• FindByPos recupera o valor do campo chave naquele índice. A referência do campo chave usa notação # para retornar o array completo de instâncias para que FindByPos possa selecionar o elemento correto.
• SumString concatena todos os valores de message no array errors para o registro de resultado atual em uma única string, separados por ". ". Se o Salesforce retornar múltiplos erros para o mesmo registro, todos são incluídos na entrada de log.

Verificar a integração

1. Implante e execute a operação com um payload de teste que inclua pelo menos um registro válido.

2. Abra os logs de operação e confirme que os valores do campo de data na solicitação do Salesforce correspondem ao formato esperado para o tipo de campo de destino: YYYY-MM-DD para campos Date, YYYY-MM-DDTHH:MM:SSZ para campos DateTime.

3. Para testar o script de registro de erros, inclua um registro deliberadamente inválido no payload de teste (por exemplo, um registro que viole uma regra de validação do Salesforce ou que referencie um registro relacionado inexistente). Após executar a operação, verifique o log de operação para uma entrada que identifique o registro pelo valor do seu campo de chave e inclua a mensagem de erro do Salesforce.

4. No Salesforce, confirme que os registros válidos foram criados ou atualizados conforme esperado.