Falando de componente Atividade de serviço...

O componente Atividade de serviço representa um ponto do processo onde será feita uma consulta aos dados de um serviço externo repassando esses dados para o processo.

A principal característica desse componente é sua capacidade de automatizar a execução de tarefas, facilitando a integração com sistemas externos e promovendo a eficiência do processo.

Ao configurar esse componente, é necessário selecionar um serviço já cadastrado na plataforma e editar um script JavaScript que fará o acesso aos métodos e dados desse serviço.

Com o uso das APIs hAPI e um formulário, é possível passar os dados obtidos na consulta do serviço para o processo.

Uma atividade de serviço pode ter apenas um fluxo de saída e deve ter um evento intermediário de captura de erro para onde a solicitação será enviada se ocorrer alguma inconsistência na execução do script.

Esse componente permite utilizar dois tipos de execução da consulta aos dados do serviço externo: a execução Automatizada e a execução Imediata, que são detalhadas a seguir.

** imagem**

function servicetask9(attempt, message) {
	
	//Variáveis globais com os dados do formulário
	var FOLDER_NAME = hAPI.getCardValue("txtFolderName");
	var PARENT_FOLDER_CODE = hAPI.getCardValue("txtFolderCode");
	var GROUP_CODE = hAPI.getCardValue("txtGroupCode");
	var INHERIT_SECURITY = hAPI.getCardValue("cbxInheritSecurity") == "true";
	
	//Tipo de documento pasta
	var DOCUMENT_TYPE_FOLDER = "1";
	
	//Usuário logado
	var USER_LOGGED = getValue("WKUser");
	
	//Número da solicitação para comentário uso na descrição da pasta criada
	var REQUEST_NUMBER = getValue("WKNumProces");
	
	// Descrição da pasta criada
	var ADDITIONAL_COMMENTS = "This folder was created automatically from fluig BPM - request ";
	
	//Atribuições de segurança
	var USER_ATTRIBUTION_TYPE = 1;
	var GROUP_ATTRIBUTION_TYPE = 2;
	var ALL_USER_ATTRIBUTION_TYPE = 3; 
	
	//Níveis de segurança
	var READING = 0;
	var RECORDING = 1;
	var MODIFICATION = 2;
	var ALL = 3;
	
    try {
    	
    	//Instancia um novo documento e define as propriedades básicas
    	var dto = docAPI.newDocumentDto();
        dto.setDocumentDescription(FOLDER_NAME);
        dto.setAdditionalComments(ADDITIONAL_COMMENTS + REQUEST_NUMBER);
        dto.setDocumentType(DOCUMENT_TYPE_FOLDER);
        dto.setParentDocumentId(parseInt(PARENT_FOLDER_CODE));
        dto.setInheritSecurity(INHERIT_SECURITY);
        
        /*
         Como é possível definir várias permissões, é necessário criar um array com todas as permissões
         que serão aplicadas. Cada item do array é uma permissão ou restrição
        */
        var dtosSecurity = new Array();
        
        //Definindo permissão total para grupo
        var dtoGroupSecurity = docAPI.newDocumentSecurityConfigDto();
        dtoGroupSecurity.setAttributionType(GROUP_ATTRIBUTION_TYPE);
        dtoGroupSecurity.setAttributionValue(GROUP_CODE);
        dtoGroupSecurity.setPermission(true);
        dtoGroupSecurity.setShowContent(true);
        dtoGroupSecurity.setSecurityLevel(ALL);

        //Definindo permissão total para usuário
        var dtoUserSecurity = docAPI.newDocumentSecurityConfigDto();
        dtoUserSecurity.setAttributionType(USER_ATTRIBUTION_TYPE);
        dtoUserSecurity.setAttributionValue(USER_LOGGED);
        dtoUserSecurity.setPermission(true);
        dtoUserSecurity.setShowContent(true);
        dtoUserSecurity.setSecurityLevel(ALL);
        
      //Definindo permissão de modificação para todos os usuários
        var dtoAllUsersSecurity = docAPI.newDocumentSecurityConfigDto();
        dtoAllUsersSecurity.setAttributionType(ALL_USER_ATTRIBUTION_TYPE);
        dtoAllUsersSecurity.setAttributionValue(""); //Para todos os usuários deve-se passar vazio 
        dtoAllUsersSecurity.setPermission(true);
        dtoAllUsersSecurity.setShowContent(true);
        dtoAllUsersSecurity.setSecurityLevel(MODIFICATION);

      //Definindo restrição para usuário
        var dtoGroupRestrictionSecurity = docAPI.newDocumentSecurityConfigDto();
        dtoGroupRestrictionSecurity.setAttributionType(GROUP_ATTRIBUTION_TYPE);
        dtoGroupRestrictionSecurity.setAttributionValue(GROUP_CODE);
        dtoGroupRestrictionSecurity.setPermission(false);
        dtoGroupRestrictionSecurity.setShowContent(true);
        dtoGroupRestrictionSecurity.setSecurityLevel(MODIFICATION);
        
        //Definindo restrição para todos os usuários
        var dtoAllUsersRestrictionSecurity = docAPI.newDocumentSecurityConfigDto();
        dtoAllUsersRestrictionSecurity.setAttributionType(ALL_USER_ATTRIBUTION_TYPE);
        dtoAllUsersRestrictionSecurity.setAttributionValue("");
        dtoAllUsersRestrictionSecurity.setPermission(true);
        dtoAllUsersRestrictionSecurity.setShowContent(true);
        dtoAllUsersRestrictionSecurity.setSecurityLevel(RECORDING);
        
        //Adicionando permissões no array de segurança
        dtosSecurity.push(dtoGroupSecurity);        
        dtosSecurity.push(dtoUserSecurity);
        dtosSecurity.push(dtoAllUsersSecurity);

        //Adicionando restrições no array de segurança
        dtosSecurity.push(dtoGroupRestrictionSecurity);
        dtosSecurity.push(dtoAllUsersRestrictionSecurity);
       
        var FOLDER = docAPI.createFolder(dto, dtosSecurity, null);
        log.info("Folder successfully createad: ID :" + FOLDER.getDocumentId());
        
    } catch (e) {
        log.error("Could not create folder: \n" + e);
    }	
}

Execução automatizada

A execução automatizada determina que a execução do script será feita de forma assíncrona e sem a necessidade de uma interação manual de uma pessoa. Nesse tipo de execução, é possível definir o número de tentativas de execução e uma mensagem de sucesso que será exibida quando a execução for concluída sem inconsistências.

Quando a solicitação chega em uma atividade de serviço com execução automatizada, ela fica parada nesse ponto até que o scritp seja executado com sucesso ou até que ele seja executado o número de vezes definido como tentativas de execução.

Se o script for executado com sucesso, a atividade de serviço é considerada concluída e a solicitação segue o seu fluxo de saída padrão. Porém, se o número de tentativas for atingido sem que haja uma execução do script com sucesso, a solicitação é movimentada para o evento intermediário de captura de erro que, por sua vez, movimentará a solicitação para o fluxo correspondente à etapa de tratamento do erro.

Em atividades de serviço com a forma de execução automatizada, é obrigatório o uso do evento intermediário de captura de erro anexado a ela, bem como um fluxo de saída deste evento, para permitir que o processo seja desviado quando o script de integração não for executado com sucesso em nenhuma das tentativas feitas.

O script da próxima execução – depois de uma execução com inconsistência – pode receber a quantidade de tentativas de execução e a mensagem da última execução como parâmetros, podendo ser utilizados dentro do script. Dessa forma, o script ficaria conforme o exemplo abaixo:

function servicetask9(attempt, message) {
    log.info("Exemplo servicetask");
    var a = hAPI.getCardValue("campo_no_formulario");
    if (a == "1") {
        return true;
    } else {
        throw "Exemplo de Erro";
    }
}

Tanto a mensagem de sucesso quanto as mensagens de inconsistências são salvas no histórico da solicitação como complementos, podendo ser vistas por quem tiver acesso à solicitação.

A execução automatizada deve ser utilizada quando a execução não necessita de um retorno imediato sobre a operação ter sido ou não executada com êxito. Essa execução é mais indicada para integração com serviços que podem ficar indisponíveis ou externos e que, necessariamente, devem ser assíncronos, fornecendo um fluxo de contingência quando a integração não for concluída com sucesso em nenhuma tentativa por qualquer motivo.

O fluxo de contingência é criado anexando um evento intermediário de captura de erro à atividade de serviço (o evento deve ser colocado em cima da atividade). Esse fluxo de saída será utilizando quando todas as tentativas de integração falharem.

Execução imediata

A execução imediata determina que a execução do script será feita de forma síncrona, logo depois do evento afterStateEntry do processo em questão, ou seja, será executado no momento em que a solicitação chegar na atividade de serviço.

Quando o script for executado com sucesso, a solicitação é enviada imediatamente da atividade de serviço para a próxima etapa, dando continuidade ao fluxo de saída padrão. Porém, se ocorrer alguma inconsistência, esta forma de execução apenas retornará a inconsistência encontrada, mantendo a solicitação parada até que uma pessoa interaja na solicitação para averiguar e corrigir as inconsistências que ocorreram.

Esse é um exemplo de código para iniciar a integração com o serviço configurado no componente:

try {
    var Service = ServiceManager.getService('rm');
    var serviceHelper = Service.getBean();
    var serviceLocator = serviceHelper.instantiate('classe.locator');
} catch(erro) {
    log.error(erro);
}

A execução imediata deve ser utilizada quando a execução necessita de um retorno imediato sobre a operação para que o processo possa seguir adiante.

Headers 

No contexto do componente Atividade de serviço, os headers (cabeçalhos) representam informações adicionais ou metadados que são enviados junto com a requisição de um serviço. Eles são usados para fornecer contexto ou parâmetros extras que o serviço ou a operação que está sendo chamada pode precisar para processar a requisição.

Os headers são frequentemente usados em chamadas de APIs REST ou SOAP e permitem adicionar informações cruciais para a comunicação entre sistemas. Cada chave/valor tem um propósito específico e a definição correta desses headers pode ser fundamental para o sucesso da integração com o serviço. Eles permitem personalizar ou configurar as requisições e, muitas vezes, podem ser obrigatórios para que o serviço funcione corretamente.

Esses headers podem ser usados para várias finalidades, dependendo do tipo de serviço e da operação. Alguns exemplos comuns de headers são:

• Autenticação e autorização: pode ser um token de autenticação, uma chave de API ou credenciais de um usuário.

  Chave: Authorization Valor: Bearer token_de_acesso

• Informações de rastreio: dados sobre a requisição que podem ser usados para monitoramento ou rastreamento da chamada do serviço.

  Chave: X-Request-ID Valor: 12345

• Informações de contexto: dados que definem o contexto da requisição, tais como o idioma, a localidade ou a versão da API.

  Chave: Accept-Language Valor: pt-BR

• Formato dos dados: definição sobre como os dados devem ser interpretados ou enviados, como o tipo de conteúdo (Content-Type) ou a versão da API.

  Chave: Content-Type Valor: application/json

Parâmetros

No contexto do componente Atividade de serviço, os parâmetros são valores ou variáveis que o método/operação precisa receber para funcionar corretamente. Cada método/operação de um serviço geralmente tem uma lista de parâmetros que precisam ser fornecidos para que a execução da ação seja bem sucedida. Sendo assim, o objetivo de configurar esses parâmetros é fornecer as informações necessárias para que o método/operação execute a ação corretamente.

Esses parâmetros podem ser de diversos tipos, como números, textos, datas ou até mesmo objetos, que são uma estrutura de dados mais complexa.

Além de fornecer os dados essenciais para a execução do método/operação, outros objetivos da configuração dos parâmetros podem envolver:

• a definição do contexto da execução: os parâmetros podem determinar o contexto no qual a operação será executada.

  Um parâmetro de "idioma" pode ser usado para alterar o idioma de uma resposta ou para personalizar a resposta do serviço com base na localização do usuário.

• a comunicação eficiente entre sistemas: quando diferentes sistemas estão interagindo, é essencial que os parâmetros estejam corretamente configurados para que a comunicação e o entendimento entre eles ocorra corretamente.

  Se um serviço externo precisa de um código de produto para retornar informações sobre ele, esse código precisa ser passado corretamente como um parâmetro.

• o mapeamento de dados: permite mapear valores provenientes de outras etapas do processo.

  Um parâmetro pode ser alimentado com o valor presente no formulário do processo preenchido em uma etapa anterior, como um número de pedido ou o ID de um cliente.

Por isso, a configuração dos parâmetros do método/operação é essencial para a correta execução da ação e comunicação entre os sistemas envolvidos.

Retorno

No contexto do componente Atividade de serviço, o retorno são 

Parâmetro de Saída: Em alguns casos, a operação pode retornar dados como resultado, e você pode mapear esses parâmetros de saída para usá-los em outra parte do processo.

• Exemplo:

  • ID do Usuário: 12345 (valor retornado pela operação)

Configurar componente Atividade de serviço – Rest

01. No diagrama do processo, clique no componente Atividade de serviço que deseja configurar com um serviço do tipo Rest.

02. Na aba Geral, defina as informações gerais para o componente que representa uma consulta de dados de um serviço externo.

03. Clique em Configurar integração.

04. Na aba Geral, defina as informações solicitadas para configurar a integração com o serviço.

05. Em Header, clique em Adicionar header para adicionar informações adicionais à requisição do serviço.

06. Insira os dados necessários para cada header.

Chave: Content-Type
Valor: application/json

07. Clique na aba Parâmetros para configurar os parâmetros do método/operação.

08. Na coluna Origem do valor de cada parâmetro, selecione de onde será obtido o valor que será passado para esse parâmetro do método/operação.

09. Clique em Salvar rascunho – localizado no lado direito da barra superior – para salvar as configurações feitas no componente Atividade de serviço.

10. Na mensagem exibida, clique em Ok, entendi.

Configurar integração

01. No diagrama do processo, clique no componente Atividade de serviço para o qual deseja configurar a execução automatizada.

02. Clique em Adicionar condição.

03. Em Nome da condição, insira um nome para identificar a condição simples depois de criada.

04. Selecione o tipo Condição simples.

05. Xxxxxxx

06. Clique em Salvar.

07. Ao concluir a inclusão de todas as condições simples desejadas, clique em Fechar– localizado no canto superior direito.

08. Clique em Salvar rascunho – localizado no lado direito da barra superior – para salvar as alterações feitas no componente Atividade de serviço.

09. Na mensagem exibida, clique em Ok, entendi.

Editar integração

01. No diagrama do processo, clique no componente Exclusivo  do qual deseja editar uma condição simples.

02. Em Condições criadas, localize a condição que deseja editar e clique em Ações– localizado no seu lado direito.

03. Clique em Editar.

04. Xxxxxxxxxx.

09. Clique em Salvar rascunho – localizado no lado direito da barra superior – para salvar as alterações feitas no componente Atividade de serviço.

10. Na mensagem exibida, clique em Ok, entendi.

Dúvidas frequentes

Confira aqui algumas dúvidas frequentes sobre o componente Atividade de serviço.

<script>
    (function() {
        function toggleAreas(isExpand, $parent) {
            var $items = $parent.find('.panel');

            $.each($items, function(idx, el) {
                var $arrow = $(el).find('span.cloakToggle').find('span');
                var $content = $(el).find('span.cloak');
                if (isExpand) {
                    $arrow.removeClass('cloakDefaultOpen').addClass('cloakDefaultClose');
                    $content.show();
                } else {
                    $arrow.addClass('cloakDefaultOpen').removeClass('cloakDefaultClose');
                    $content.hide();
                }
            });
        }

        $(document).on('click', '#toggleAll-3', function(ev) {
            ev.preventDefault();
            var isExpand = $(this).data('expand');
            var $parent = $(this).nextAll('.sectionColumnWrapper').first();
            toggleAreas(isExpand, $parent);
            $(this).data('expand', !isExpand);
        });
    })();
</script>
<a id="toggleAll-3" href="#" data-expand="true">Abrir/fechar todas as dúvidas</a>

<!-- Hotjar Tracking Code for http://tdn.totvs.com/display/fb -->
<script>
    (function(h,o,t,j,a,r){
        h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
        h._hjSettings={hjid:1280165,hjsv:6};
        a=o.getElementsByTagName('head')[0];
        r=o.createElement('script');r.async=1;
        r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
        a.appendChild(r);
    })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
</script>