INTERFACES DOS COMPONENTES X-GOV COM OS WEBSERVICES DO GOVERNO

Transcrição

1 ESPECIFICAÇÃO DAS INTERFACES DOS COMPONENTES X-GOV COM OS WEBSERVICES DO GOVERNO Relatório Técnico Este documento contém especificações dos métodos para a implementação de cada padrão de tarefa definido no documento X-Gov Task Patterns e deve ser utilizado como referência para a construção das interfaces de troca de dados (WebServices) entre as agencias governamentais e a camada de modelo do Framework X-Gov. André Quintella Bertuzzi Leonardo Alexandre Ferreira Leite Flavio Miyamaru Lucia Filgueiras Novembro de 2008 Grupo de Estudos em interação do LTS Escola Politécnica da Universidade de São Paulo

2 ESPECIFICAÇÃO DAS INTERFACES DOS COMPONENTES X-GOV COM OS WEBSERVICES DO GOVERNO Relatório Técnico CONTROLE DE REVISÕES No. Data Revisão

3 Sumário Introdução... 4 Métodos dos Padrões de Tarefas Obtain pre-service information Submit information to government Submit personal information Find public information Find information about some entity Find private information Get digitally certified document Create an invoice Verify document validity Print document Save as file Authentication Get track id Pay fee/tax Schedule Talk to the ombudsman Receive a message Track a process Como transformar os padrões em WebServices? Referências... 24

4 Introdução Dentro do projeto X-Gov [1] há a necessidade de uma troca de dados constantemente entre o framework e o governo, buscando informações sobre determinadas entidades/pessoas/serviços ou enviando essas informações. Para isso, é necessário implementar interfaces de comunicação entre ambas as partes que não dependam da plataforma de origem ou destino. Este documento contém especificações dos métodos para a implementação de cada padrão de tarefa definido no documento X-Gov Task Patterns e deve ser utilizado como referência para a construção das interfaces de troca de dados (WebServices) entre as agencias governamentais e a camada de modelo do Framework X-Gov. Para o acompanhamento do documento a seguir o leitor deve ler antes os seguintes documentos: X-Gov Task Patterns que pode ser encontrado no seguinte endereço X-gov planning: how to apply cross media to government services. Além disso, é necessário que o leitor tenha noções básicas dos seguintes tópicos: Programação Orientada a Objetos WebServices O documento está estruturado da seguinte forma: X - Título do padrão de tarefa X.x - numeração do método método: nome do método chamada: nomedachamadadometodo(parâmetros de entrada): Objetoderetorno{parâmetros do objeto de retorno} lista contendo as especificações dos parâmetros de entrada lista contendo as especificações dos parâmetros de retorno descrição do método explicando suas gereralizações e especificidades exemplo de chamada do método com parâmetros de entrada e de retorno. Exemplo do padrão 17:

5 sendmessage("usuario", "senha", "Carlos", " ","Olá","Olá amigo","sms") ["Erro 551: Usuário ou senha incorreto(s)",null] Dentro desse documento citamos também o conceito do xid. O xid consiste na identificação do cidadão que através dela, poderá utilizar os diversos serviços oferecidos pelo governo. A princípio não é definido quais as variáveis que consiste essa identificação e por isso ela é tratada como um objeto da classe Xid.

6 Métodos dos Padrões de Tarefas 1 - Obtain pre-service information 1.a método: obter dados chamada: preservicepurchasedata(): Page[] {int id, int pass, String title, String text, String mediaurl, String type} sem parâmetros de entrada Page[]: array de objetos da classe Page Atributos da classe Page: id identificador único do registro pass ordem da página na sequência determinada title título da página text texto conteúdo da página mediaurl url de mídia auxiliar type tipo da mídia auxiliar O atributo type pode receber os valores {"text", "image", "video", "sound"}, que representam respectivamente texto, imagem, vídeo e som. Retorna uma lista de elementos (array), em que cada elemento (Page) possui o título, texto, url de conteúdo multi-mídia e tipo deste conteúdo. Caso o conteúdo seja do tipo texto, entende-se que não há mídia auxiliar. preservicepurchasedata() Array de objetos Page retornado: {[111, 1, "Bem vindo!", "Bem vindo a prova de conceito...", "wellcome.mpeg", "video"] ; [112, 2, "Passo 1", "Escolha a escola do seu fiho através...", "soundtrack.mp3", "sound"] ; [113, 3, "Passo 2", "Vá conversar pessoalmente com a diretora...", "soundtrack.mp3", "sound"] ; [114, 4, "Pronto!", "Seu filho já está matriculado!", null, "text"] } 1.b método: obter um passo da seqüência chamada: preservicepurchasepage(int pass): Page {int id, int pass, String title, String text, String mediaurl, String type} pass ordem da página na sequência determinada

7 Um objeto da classe Page. Atributos da classe Page: id identificador único do registro pass ordem da página na sequência determinada title título da página text texto conteúdo da página mediaurl url de mídia auxiliar type tipo da mídia auxiliar O atributo type pode receber os valores {"text", "image", "video", "sound"}, que representam respectivamente texto, imagem, vídeo e som. Retorna a página requisitada, que possui possui o título, texto, url de conteúdo multi-mídia e tipo deste conteúdo. Caso o conteúdo seja do tipo texto, entende-se que não há mídia auxiliar. preservicepurchasepage(2) [112, 2, "Passo 1", "Escolha a escola do seu fiho através...", "soundtrack.mp3", "sound"] 2 - Submit information to government 2.a método: enviar informação chamada: submitinfo(string param1, String param2,..., String paramn): SubmitedResult{boolean success, int id) paramn conteúdo de um dos campos do formulário Um objeto da classe SubmitedResult, contendo um valor booleano (success) com a seguinte codificação: true sucesso false falha além de um id que é o identificador do cadastro. O serviço deve cadastrar os dados do formulário no banco de dados apropriado.

8 submitinfo("12/12/2008", "23:40", "assalto", "celular, dinheiro, tênis", "prç Caxias") [true,3354] Neste caso podemos imaginar o registro de um BO 3 - Submit personal information 3.a método: enviar informação chamda: submitpersonalinfo(xid xid, String param1, String param2,..., String paramn): SubmitedResult{boolean success, int id) xid identidade do usuário paramn: conteúdo de um dos campos do formulário Um objeto da classe SubmitedResult, contendo um valor booleano (success) com a seguinte codificação: true sucesso false falha além de um id que é o identificador do cadastro. O serviço deve cadastrar os dados do formulário no banco de dados apropriado. submitinfo(xid, "Beatriz Quintela", "04/02/1991", "Rua Aurora nº 105", "São Bernardo do Campo", "São Paulo") [true,2212] 4 - Find public information 4.a método: Buscar lista de informações chamada: searchentitylist(string name): EntitySearchResult[] {int id, String info1,..., String info2} name: string contendo o termo a ser procurado

9 Array dos resultados e de seus respectivos IDs Faz uma busca de entidades por uma String, de forma que podemos ter vários resultados para a busca. As strings retornadas não precisam conter todas as informações da entidade. O id é necessário para a criação de links para futura requisição da mesma entidade. searchentitylist("andrade") {[1324, "EE Mário de Andrade"] ; [1354, "EE Oswald de Andrade"]} Neste caso podemos imaginar uma busca por escolas. 4.b método: Buscar entidade por Id chamda: findentity(int id): String[] id identificador da entidade requisitada Array com as informações da entidade Array é null em caso de id passado não existir Faz uma busca por uma determinada entidade através de seu id. As strings retornadas devem conter todas as informações da entidade. searchentitylist(1324) ["EE Mário de Andrade", "rua Manoel da Nóbrega, n 465"] Neste caso podemos imaginar uma busca por escolas. 5- Find information about some entity 5.a método: Buscar lista de informações chamda: searchentitylist(string name): EntitySearchResult[] {int id, String info1,..., String info2}

10 name string contendo o termo a ser procurado Array dos resultados e de seus respectivos IDs Faz uma busca de entidades por uma String, de forma que podemos ter vários resultados para a busca. As strings retornadas não precisam conter todas as informações da entidade. O id é necessário para a criação de links para futura requisição da mesma entidade. searchentitylist("miyamaru") {[3224, "Flavio Miyamaru"] ; [3254, "Renata Hito Miyamaru"]} Neste caso podemos imaginar uma busca por carros apreendidos 5.b método: Buscar entidade por Id chamda: findentity(int id): String[] id identificador da entidade requisitada Array com as informações da entidade Array é null em caso de id passado não existir Faz uma busca por uma determinada entidade através de seu id. As strings retornadas devem conter todas as informações da entidade. searchentitylist(3254) ["Renata Hito Miyamaru", "Gol", "verde", "1999", "23/10/2008", "R$576,54"] Neste caso podemos imaginar uma busca por carros apreendidos 6- Find private information 6.a

11 método: Buscar lista de informações chamda: searchentitylist(xid xid, String name): EntitySearchResult[] {int id, String info1,..., String info2} xid: identificação do usuário name: string contendo o termo a ser procurado Array dos resultados e de seus respectivos IDs Faz uma busca de entidades por uma String, de forma que podemos ter vários resultados para a busca. As strings retornadas não precisam conter todas as informações da entidade. O id é necessário para a criação de links para futura requisição da mesma entidade. Deve-se antes executar a tarefa de autenticação. Dados trafegados devem ser seguros (criptografados e/ou o que for preciso). searchentitylist(xid, "PCS") {[4224, "PCS 2359"] ; [4254, "PCS 2354"] [4256, "PCS 3244"]} Neste caso podemos imaginar uma busca pela situação do aluno na disciplina 6.b método: Buscar entidade por Id chamda: findentity(xid xid, int id): String[] xid identificação do usuário id identificador da entidade requisitada Array com as informações da entidade Array é null em caso de id passado não existir Faz uma busca por uma determinada entidade através de seu id. As strings retornadas devem conter todas as informações da entidade. Deve-se antes executar a tarefa de autenticação. Dados trafegados devem ser seguros (criptografados e/ou o que for preciso). searchentitylist(xid, 4254)

12 ["PCS 2354", "Aprovado", "4", "6,3", "2007"] Neste caso podemos imaginar uma busca pela situação do aluno na disciplina 7- Get digitally certified document 7.a método: obter dados documento chamda: retrievedocumentinfo(int id): String[] id identificador do documento Um array de strings com os campos do documento. O webservice deve retornar as informações que caracterizam completamente o documento. A aplicação cliente deve conhecer a estrutura do documento para que possa meramente preencher o esqueleto com dados fornecidos. validatedocument(14232) ["João Ricardo da Silva", " ", "rua Maria de Barros, n 23", "R$ ", "Mário Cândido de Pena", " "] Neste caso podemos imaginar um comprovante de que João comprou uma casa de Mário. 8 - Create an invoice 8.a método: obter dados do boleto chamda: retrieveinvoiceinfo(int id): String[] id: identificador do boleto Um array de strings com os campos do boleto. O webservice deve retornar as informações (valor, prazo, juros, banco etc) que caracterizam completamente o boleto.

13 A aplicação cliente deve conhecer a estrutura do boleto para que possa meramente preencher o esqueleto com dados fornecidos, encarregando-se inclusive da geração do código de barras. Obs: Na verdade este método é praticamente igual ao retrievedocumentinfo(), no entanto os valores retornados já serão padronizados (sendo para isso antes necessário um estudo sobre boletos). A camada de interface também já terá uma implementação específica e reutilizável para qualquer aplicação, em contraste com o task-pattern anterior. validatedocument(1182) ["R$132,87", "22/02/2009", "5,1%", "Nossa Caixa S/A"] Neste caso podemos imaginar um comprovante de que João comprou uma casa de Mário. 9 - Verify document validity 9.a método: checar autenticidade chamada: validatedocument(int id): DocumentValidityResult {boolean validity, String docinfo1,..., String docinfon} id: identificador do documento Objeto da classe DocumentVaidityResult, contendo um valor boolean (validity) em que true documento válido false documento inválido além das strings com os campos do documento checado. O webservice deve checar, pelo id, se um determinado documento é válido. No caso de ser válido, deve retornar as informações que caracterizam aquele documento (strings docinfo), para que o usuário possa ter certeza de que a validação se refere ao seu documento. No caso de ser inválido, deve-se retornar o valor null para as strings docinfo. É função do cliente saber o que significa cada string, dado seu posicionamento na sequência de strings, assim como é função do webservice ordenar corretamente as strings com as informações desejadas.

14 validatedocument(14232) [true, "João Ricardo da Silva", " ", "rua Maria de Barros, n 23", "R$ ", "Mário Cândido de Pena", " "] Neste caso podemos imaginar um comprovante de que João comprou uma casa de Mário Print document Não possui relação com o webservice 11 - Save as file Não possui relação com o webservice 12 - Authentication 12.a método: autenticar chamada: authenticate(xid xid, String password): boolean Xid identificação do usuário password senha de acesso true: sucesso false: falha O webservice deve verificar a autenticidade da identificação do usuário, através de parâmetros passados pelo cliente. Obs: por enquanto sugerimos simplesmente uma senha, mas o método de autenticação pode ser algo mais complexo, que ainda deve ser especificado. authenticate(xid, "msltsep") false

15 13 - Get track id 13.a método: obter código de processo chamada: generatetrackid(xid xid, int id): int xid: identificação do usuário id: identificador do processo número de acompanhamento O webservice deve retornar um código de acompanhamento para que o usuário possa futuramente checar o estado de seu processo. Deve-se antes executar a tarefa de autenticação. generatetrackid(xid, ) Pay fee/tax 14.a método: obter informação chamada: purchasepaymentinfo(): Page {int id, int pass, String title, String text, String mediaurl, String type} sem parâmetros de entrada Um objeto da classe Page. Atributos da classe Page: id identificador único do registro pass ordem da página na sequência determinada title título da página text texto conteúdo da página mediaurl url de mídia auxiliar type tipo da mídia auxiliar O atributo type pode receber os valores {"text", "image", "video", "sound"}, que representam respectivamente texto, imagem, vídeo e som.

16 O cliente requisita informações de como proceder com o pagamento de um determinado serviço de governo e o webservice retorna as informações requisitadas. O funcionamento deste método é idêntico ao preservicepurchasepage. purchasepaymentinfo() [152, 1, "Pagando", "Vá até a agência bancária mais próxima...", null, "text"] 14.b método: pagar chamada: pay(xid xid, int id): PaymentResult{boolean success, int id} Xid: identificação do usuário id: identificador do processo (se necessário) Um objeto da classe PaymentResult, contendo um valor booleano (success) com a seguinte codificação: true sucesso false falha além de um id que é o identificador do pagamento. O pagamento pode ser feito por cartão de crédito (caso mais comum) ou direto da conta corrente, como se fosse cartão de débito (ex: caso do Enem com Banco do Brasil) Em ambos os casos o serviço não possui controle sobre o tráfego de informações entre banco e cidadão O comprovante deve ser retornado tanto para o cidadão quanto para o governo (espera-se que normalmente seja a instituição bancária que forneça o comprovante ao usuário) O serviço de governo também deve armazenar a identidade do cidadão que efetua o pagamento, assim como data, hora e forma de pagamento (possivelmente também número da conta ou do cartão de crédito) Obs: o task pattern atual não contempla o método "pagar" pay(xid, 33342) [true,44455]

17 15 - Schedule 15.a método: agendar chamada: requestschedule(xid xid, int process, String date, String time, int scheduled): ScheduleResult{string answer, int id} xid identificador do agendador process identificador do processo (se necessário) date data desejada time hora desejada scheduled identificador do agendado Um objeto da classe ScheduleResult. Atributos da classe ScheduleResult: answer resposta da requisição, ela pode informar se ocorreu erro e o tipo de erro ocorrido bem como o sucesso no agendamento. id identificador do agendamento O webservice deve ser responsável por checar a disponibilidade de horários na base de dados apropriada para agendar um evento. O método chama o webservices com o parâmentro de identificador e Obs: agendador = pessoa que se beneficia do agendamento (ex: paciente que vai se conultar ou aluno que está se matriculando) agendado = entidade que o agendador procura (ex: médico que atende o paciente ou escola onde aluno está se matriculando) requestschedule(xid, 3323, "04/05/2009", "16:00", 176) ["A sua consulta foi marcada no dia desejado, com o médico desejado, porém o horário deve ser 17:30", ] 15.b método: obter todos os agendamentos chamada: retrieveallschedules(xid xid): ScheduleResult[] {int id, int process, String date, String time, int scheduled} xid - identificação do usuário ScheduleResult[]: array de objetos da classe ScheduleResult

18 Atributos da classe ScheduleResult: id identificador do agendamento process identificador do processo date data desejada time hora desejada scheduled identificador do agendado Cliente requisita ao webservice que informe os agendamentos que o usuário tem marcado para um determinado serviço. O webservice retorna um array com informações dos agendamentos que usuário possui. Cada agendamento é um objeto ScheduleResult. retrieveschedule(xid) {[ , 3323, "04/05/2009", "17:30", 176] [ , 3323, "07/05/2009", "13:00", 187]} 15.c método: obter agendamento chamada: retrieveschedule(xid xid, int id): ScheduleResult {int id, int process, String date, String time, int scheduled} xid - identificação do usuário id: identificador do agendamento Um objeto da classe ScheduleResult. Atributos da classe ScheduleResult: id: identificador do agendamento process: identificador do processo date: data desejada time: hora desejada scheduled: identificador do agendado Cliente requisita ao webservice que informe os agendamentos que o usuário tem marcado para um determinado serviço. O webservice retorna um array com informações dos agendamentos que usuário possui. Cada agendamento é um objeto ScheduleResult. retrieveschedule(xid, ) [ , 3323, "04/05/2009", "17:30", int scheduled]

19 16 - Talk to the ombudsman 16.a método: enviar comentário chamada: sendcomment(xid xid, string from, string sector, string subject, string text): OmbudsmanResult{string answer, int id} xid identificação do usuário from contato do cidadão através do qual o ombudman irá responder sector setor do serviço para qual se destina a mensagem subject assunto da mensagem text corpo de texto da mensagem Um objeto da classe OmbudsmanResult. Atributos da classe OmbudsmanResult: answer resposta da requisição, ela pode informar se ocorreu erro e o tipo de erro ocorrido bem como quando a dúvida, crítica ou sugestão será respondida. id identificador do comentário O método envia o comentário para um destinatário, já especificado dentro do webservices, contendo os parâmetros da mensagem (assunto, texto e remetente) definida pelo cidadão. Em seguida, há um retorno do método com informações de feedback, se a mensagem foi enviada com sucesso ou se houve algum erro, mensagem de agradecimento pelo contato e/ou um informe que a mensagem será repondida o mais breve possível. Se serviço só tiver um ombudsman, o parâmetro sector pode ser não utilizado. Chamadado método: sendcomment(xid, "caterina@serv.com", "Dúvida", "Gostaria de saber onde entregar os documentos da matrícula") ["Sua mensagem foi recebida com sucesso, aguarde e brevemente entraremos em contato", ] 17 - Receive a message 17.a método: enviar mensagem

20 chamada: sendmessage(string user, string password, string from, string to, string subject, string text, string media): MessageResult{string answer, int id} user usuário que fará a requisição do serviço password senha do usuário from remetente da mensagem to destinatário da mensagem subject assunto da mensagem text corpo de texto da mensagem media mídia para a qual será enviada a mensagem ( ,sms,mail) Um objeto da classe MessageResult. Atributos da classe MessageResult: answer resposta da requisição, ela pode informar se ocorreu erro e o tipo de erro ocorrido id identificador da mensagem O método envia as informações necessárias (nome do usuário, senha, remetente, destinatário, assunto da mensagem, texto e a mídia) para o webservices realizar o envio da mensagem na mídia escolhida. Como retorno do método temos uma resposta informando se foi possível o envio da mensagem e um id identificando a mensagem enviada. Caso algum parâmetro de entrada esteja errado ou a mensagem não conseguir ser enviada a resposta do método informa o erro ocorrido para o possível tratamento e o id retornado vem como null. Diferentemente do padrão anterior, o destinatário nesse caso é o cidadão para qual o governo deseja enviar uma mensagem. Exemplo 1: sendmessage("usuario", "senha", "Carlos", " ","Olá","Olá amigo","sms") ["Erro 551: Usuário ou senha incorreto(s)",null] Exemplo 2: sendmessage("usuario", "senha", "André", beatriz@bol.com.br","olá","oi bia"," ") ["Mensagem enviada com sucesso", ]

21 18 - Track a process 18. método: checar estado atual de um processo chamada: trackprocess(int tracknumber): Process {int id, string title, string text, bool status} track number Um objeto da classe Process. Atributos da classe Process: id identificador único do processo title título do processo text texto do conteúdo do processo status status atual do processo (true - OK, false - o processo tem alguma pendência) O método retorna um objeto da classe Process contendo as informações básicas de um processo e o seu status atual. Caso o processo não exista retorna null. O método pode ser implementado para retornar apenas o identificador do processo retornando null nos outros parâmentros. trackprocess( ) Retorno do Método: [ , "Processo de Matrícula Escolar", "Sua matrícula está pendente, para maiores informações disque (11) ", false]

22 Como transformar os padrões em WebServices? Até aqui procuramos definir os métodos que serão requisitados pelo framework X-Gov de forma mais geral, independente da aplicação. No entanto, cada aplicação terá especificidades em particular, que deverão ser definidas durante a modelagem do serviço x-gov. Em primeiro lugar, vemos que há métodos em que são passados um conjunto de strings, como no caso do cadastro e de obter documento, sendo que esse conjunto de strings deve ser definido de acordo com as regras do negócio do serviço em questão. Exemplo: Especificação genérica: submitinfo(string param1, String param2,..., String paramn): SubmitedResult{boolean success, int id} Especificação específica: submitinfo(string nome, String cargo, String salario, String dataadmissao): SubmitedResult{boolean success, int id} Uma vez estabelecida essa regra, é preciso estar ciente de que essa configuração é de conhecimento tanto do cliente quanto do webservice, o que quer dizer que uma atualização do sistema deve contemplar ambos os lados. Esse mesmo problema de atualização dos dois lados ocorre para o caso em que o desenvolvedor opte por interfaces diferentes das propostas pelo framework, descritas neste documento. Em ambos os casos de adaptação da interface, também temos a situação em que o desenvolvedor terá que alterar o código dos elementos gerados pelo framework. Lembramos que a idéia da especificação das interfaces descrita neste documento é jogar o máximo possível das regras de negócio para o webservice, de modo que em alguns casos, para atualizar o sistema, basta uma atualização do webservice. Mas como acabamos de ver isto não é sempre possível. Essa é outra questão que deve ser pensada pelo desenvolvedor do serviço quando for completar a estrutura do componente de interface indicada pelo framework, assim como determinar as tarefas do webservice. Um segundo ponto que colocamos é o cuidado que se deve ter quando o serviço de governo necessita utilizar duas vezes o mesmo componente para diferentes tipos de resultado. Isso leva a uma necessidade de se distribuir os métodos do serviço de governo em mais de um webservices. Imaginando um serviço de governo que faz uma busca por escolas e hospitais, podemos distribuir essas duas requisições em webservices diferentes, fazendo com que no cliente tenhamos as duas chamadas distintas: escolaswebservice.searchentitylist("mário de Andrade"); hospitaiswebservice.searchentitylist("oswaldo Cruz"); Sendo escolaswebservice e hospitaiswebservice objetos diferentes que representam webservices diferentes.

23 Portanto, faz parte do projeto do serviço de x-gov o planejamento da distribuição das requisições em diferentes webservices, lembrando que uma distribuição adequada pode até mesmo facilitar a manutenção e evolução da aplicação, enquanto que uma distribuição mau feita, pode dificultar esses mesmos aspectos.

24 Referências [1] Filgueiras, L. V., Correa, D. O., Neto, J. S., and Facis, R. P X-Gov Planning: How to Apply Cross Media to Government Services. In Proceedings of the Second international Conference on Digital Society (February 10-15, 2008). ICDS. IEEE Computer Society, Washington, DC,