Olá, Comunidade!

Este artigo fornece uma visão geral dos webservices JSON REST desenvolvidos pelo TrakCare.

Esses webservices permitem aos usuários acessar os dados do TrakCare fora do software, principalmente por apps externos.

 

Eles são desenvolvidos em REST com ObjectScript e permitem o acesso aos dados em quatro modos:

• Listar: reúne uma lista de dados com base em um filtro (por exemplo, todos os episódios de um determinado paciente);
• Abrir: obtém uma linha específica do ID interno ou de uma chave única (por exemplo, o número de um determinado episódio);
• Salvar: insere uma nova entrada na tabela correta e retorna o ID interno;
• Atualizar: atualiza uma entrada existente em uma tabela com base no ID.

 

Acesso aos webservices

O URL genérico para os webservices é:

http://<adresse IP ou alias du serveur TrakCare>:57772/trakRestWS/tcrest/call

As solicitações são enviadas pelo método POST, com um corpo JSON contendo os dados de autenticação do usuário, a identificação do webservice que será chamado (classe e método) e os parâmetros de método. Esses parâmetros são, na maioria das vezes:

• para webservices Listar, o número do episódio;
• para Abrir, o ID interno do elemento;
• para Salvar, os campos obrigatórios para a inserção de um novo elemento, mais o contexto e ação ACN associados e os parâmetros não obrigatórios;
• para Atualizar, o ID interno do elemento e os campos a serem atualizados.

A estrutura JSON é a seguinte:

{
    "ClassName": "<Full class name>",
    "MethodName": "<Method name, generally List, Open, Save, SaveWithACN or Update>",
    "AppName": "<Name of the application calling the webservice>",
    "Request": {
        "UserName": "<TrakCare username>",
        "Password": "<Encoded password>",
        "Encoder": "Base64",
        "Params": {
            <Parameters>
        }
    }
}

O parâmetro Encoder define a codificação da senha, o que impede o envio da senha do usuário sem criptografia. Porém, se o parâmetro Encoder não estiver definido, o campo Password conterá a string não codificada da senha do usuário.

 

Filtros

Os webservices Listar e Abrir geralmente retornam grandes volumes de dados, o que pode fazer com que os aplicativos clientes fiquem lentos. Assim, um sistema de filtragem de resultado do webservice é possível se outro parâmetro for adicionado ao JSON.

A filtragem é possível obtendo apenas uma lista de campos solicitados com o parâmetro FilterInclude ou excluindo os campos não desejados com FilterExclude. O JSON anterior pode, portanto, ser um dos dois a seguir:

{
    "ClassName": "<Full class name>",
    "MethodName": "<Method name, generally List, Open, Save, SaveWithACN or Update>",
    "AppName": "<Name of the application calling the webservice>",
    "Request": {
        "UserName": "<TrakCare username>",
        "Password": "<Encoded password>",
        "Encoder": "Base64",
        "Params": {
            <Parameters>
        },
        "FilterInclude": "&lt;Fields to include separated by a comma>"
    }
}

OU

{
    "ClassName": "<Full class name>",
    "MethodName": "<Method name, generally List, Open, Save, SaveWithACN or Update>",
    "AppName": "<Name of the application calling the webservice>",
    "Request": {
        "UserName": "<TrakCare username>",
        "Password": "<Encoded password>",
        "Encoder": "Base64",
        "Params": {
            <Parameters>
        },
        "FilterExclude": "&lt;Fields to exclude separated by a comma>"
    }
}

 

Tabelas de código / Thesauri

As tabelas de código, ou thesauri, armazenam alguns dos dados do TrakCare. São dicionários referenciados por outras tabelas do TrakCare por código ou descrição e, portanto, necessários para o funcionamento correto dos webservices. 

Lista de tabelas de código

A lista de tabelas de códigos está disponível para o usuário ao usar o seguinte JSON:

{
    "ClassName": "Region.FRXX.WebServices.REST.CodeTables.GenericCodeTables",
    "MethodName": "List",
    "AppName": "<Name of the app calling the webservice>",
    "Request": {
        "UserName": "<TrakCare username>",
        "Password": "<Password>",
        "Params": {
            "CT": "*"
        }
    }
}

O JSON resultante conterá a lista ou os thesauri disponíveis.

Conteúdo da tabela de código

Para acessar uma tabela de código, o parâmetro dela no JSON anterior precisa conter o nome da tabela de código que queremos acessar. Dois parâmetros adicionais, Filter e FilterActif, especificam a solicitação.

Filtro

O parâmetro Filter filtra no código e na descrição os elementos na tabela de código. É baseado em um sistema de correspondência de padrão semelhante ao do SQL, usando o caractere % como curinga.

A filtragem pode ser feita de uma das seguintes maneiras:

• Filtragem estrita com uma string exata: o resultado de "Bilateral" será somente os elementos que tiverem código ou descrição correspondente a "Bilateral", sem diferenciar maiúsculas de minúsculas.
• Filtragem suave com o curinga %: o % define um grupo desconhecido de caracteres. Portanto,
  • o resultado de "%al" incluirá todos os elementos que acabam em "al" (ou "AL", "Al", "aL")
  • o resultado de "Bi%" incluirá todos os elementos que começam com "Bi" (ou "BI", "bi", "bI").
  • o resultado de "%la%" incluirá todos os elementos que tiverem código ou descrição com "al" em algum lugar (sem diferenciar maiúsculas de minúsculas).
    • nesse caso, o % pode ser combinado para a correspondência com elementos contendo várias strings, por exemplo, "%bi%al%"
  • o resultado de "%" incluirá todos os elementos. No entanto, tenha cuidado, algumas tabelas de código contêm várias linhas, o que pode causar falha ou lentidão nos aplicativos clientes.

Se o parâmetro Filter estiver em branco ou não definido, o resultado do webservice será vazio.

FilterActif

Por padrão, o webservice só gera parâmetros padrão do thesaurus como resultado. Para filtrar em elementos ativos e inativos, o parâmetro FilterActif definido com o valor "ALL" precisa ser transmitido no JSON.

Veja este exemplo completo para obter a lista de prestadores de cuidados (tabela de código CTCareProv):

{
    "ClassName": "Region.FRXX.WebServices.REST.CodeTables.GenericCodeTables",
    "MethodName": "List",
    "AppName": "Postman",
    "Request": {
        "UserName": "userWS",
        "Password": "****",
        "Params": {
            "CT": "CTCareProv",
            "Filter": "%",
            "FilterActif": "ALL"
        }
    }
}

 

ACN

O método Salvar é genérico e implementado em todos os webservices ao inserir uma nova entrada. No entanto, ele só insere a entrada na base de dados do TrakCare, e não no EPR.

O método SaveWithACN implementado por todos os webservices Salvar salva os dados na base de dados e no EPR. Esse método exige dois parâmetros adicionais: ACNContext e  ACNAction. O número do episódio (Episode) também precisa ser definido, mesmo se não for necessário para inserções típicas.

Todos os contextos podem ser obtidos na tabela de código MRCEncEntryType. Depois, a ação associada pode ser obtida ao chamar o webservice Salvar genérico e o método GetAction.

 

Exemplos finais

Vamos considerar o histórico médico familiar. Uma solicitação para listar todo o histórico médico familiar de um paciente será desta maneira:

{
    "ClassName": "Region.FRXX.WebServices.REST.PAFamily.List",
    "MethodName": "List",
    "AppName": "SoapUI",
    "Request": {
        "UserName": "userWS",
        "Password": "******",
        "Params": {
            "IPP": "21002205"
        }
    }
}

Em seguida, para obter um desses registros médicos, usaremos:

{
    "ClassName": "Region.FRXX.WebServices.REST.PAFamily.Open",
    "MethodName": "Open",
    "AppName": "SoapUI",
    "Request": {
        "UserName": "userWS",
        "Password": "demo",
        "Params": {
            "ID": "679063||2"
        }
    }
}

Para salvar um novo histórico médico no EPR, precisamos usar o seguinte JSON:

{
    "ClassName": "Region.FRXX.WebServices.REST.PAFamily.Save",
    "MethodName": "SaveWithACN",
    "AppName": "SoapUI",
    "Request": {
        "UserName": "userWS",
        "Password": "demo",
        "Params": {
            "Episode": "196001820",
            "IPP": "21002205",
            "ACNContext": "Toutes les actions",
            "ACNAction": "TC.FMHIS",
            "MRCIDCodeOrDesc": "C254",
            "FAMRelationCodeOrDesc": "10",
            "FAMDesc": "Created with a webservice"
        }
    }
}

Por fim, para atualizar esse mesmo histórico, só enviaremos os campos modificados para o método Atualizar:

{
    "ClassName": "Region.FRXX.WebServices.REST.PAFamily.Save",
    "MethodName": "Update",
    "AppName": "SoapUI",
    "Request": {
        "UserName": "userWS",
        "Password": "******",
        "Params": {
            "ID": "679063||1",
            "FAMDesc": "Updated with a webservice"
        }
    }
}

 

Conclusão

Esses webservices JSON REST permitem que aplicativos de terceiros acessem e modifiquem dados do TrakCare.

A próxima etapa seria adicionar uma camada ao Mecanismo de redirecionamento para deixar os usuários acessarem os dados com os padrões REST (separação de recursos por URL, uso de verbos HTTP, etc.)