domingo, 15 de outubro de 2017

Design de UI do futuro sem botões

O que são botões e nós realmente precisamos deles?

Desde o início das interfaces de usuário gráficas usamos botões. Considere a GUI original da Xerox PARC, que tem 44 anos - e ainda assim nossas interfaces de usuário são muito parecidas.

Recentemente, tracei o histórico de estilos de botões criando o Dribbble Timeline. Embora os botões evoluíram em sintonia com as tendências atuais e ao lado da tecnologia, sua origem é, sem dúvida, inspirada em objetos reais do passado.


Canto inferior direito - Sears First Electric Buzzer 1897 Catálogo de outono

Por mais de uma década, criamos dispositivos sem uma interface física - que não dependem do toque humano, mas podem ser ativados por voz ou gesto. Por que persistimos na criação de formas com as quais interagir com base nos objetos familiares que nos cercam? A forma de um botão digital ainda é modelada em ferramentas e mecanismos que desenvolvemos no século XIX!

Nós criamos dispositivos eletrônicos inteligentes completamente novos, podemos manipulá-los de maneira quase exclusiva, mas por falta de preguiça ou força de hábito, continuamos a forçar nossos usuários a clicar em uma pequena área de apenas alguns pixels de largura.

É hora de fazer algo sobre isso - é hora de pensar sem botão.

UI "Sem-botão" - onde tudo se interage

Uma "utopia sem botões" é um conceito em que qualquer tentativa de manter mais de 130 anos de como as coisas sempre foram feitas está completamente destruída. O futuro é agora - devemos seguir em frente e alienar-nos das soluções ultrapassadas de nossos predecessores.

É possível para nós imaginar uma interface completamente livre de botões? Algo tão intuitivo, que, apenas olhando para ele, você saberá como agir? Não precisa mais ser apenas em nossa imaginação - essas interfaces já existem.


Microsoft HoloLens: HoloTour

Podemos, de uma vez por todas, eliminar o botão venerado? Microfones, câmeras, telas sensíveis ao toque, vibrações, acelerômetros, giroscópios, GPS, realidade estendida, realidade virtual - a lista continua - e tudo isso é gerenciado pelo seu smartphone ou PC. Não há mais nenhuma razão para continuar forçando seus usuários a pressionar aquele pequeno retângulo.

Vamos eliminar botões nas IIs

Você já leu Design de Tipo - Conceito do Tópico Designer Michael Abehsera em que as interfaces são desprovidas de qualquer elemento gráfico na qual o que importa é o conteúdo? Muitos de vocês perguntaram: "E os botões?" Nós não precisamos deles mais, vamos eliminá-los completamente.

Aqui estão algumas idéias interessantes:

O Facebook simplesmente perguntou: "Qual é o seu humor?" Não é necessário pressionar um botão para responder - use sua voz - diga-lhe que se sente bem e dirija-se à praia. Em seguida, arraste o texto que o Facebook reconhece da sua resposta para onde você deseja que ele apareça.


Pesquisa por voz Neel Raj

Parecido com um artigo sobre Medium? Um tempo atrás em Medium você poderia simplesmente "recomendar" um artigo. Hoje, clicamos em "palmas". Então, "aplauda". E se não houvesse necessidade de clicar nesse pequeno botão estranho, apenas literalmente aplaudir?


Conceito sem botões de Wojciech Dobry (... Não leve isso a sério demais.)

E quanto a algumas ações mais complexas? Como um check-out em uma loja online. Arraste e solte um item no carrinho de compras, deslize para proceder ao check-out e confirme com sua impressão digital. Mole-mole.


ASOS - Adicionar ao carrinho animação por Zachary Zhao

Conteúdo que pensa e tela inteira

Vamos começar com as superfícies que atualmente tocamos para executar uma ação. Dado que a grande maioria das interfaces de usuário gráficas dos dias modernos são exibições de tela sensíveis ao toque - muitas vezes manipuladas com nossos polegares - é lógico que tais interfaces estejam conosco por um longo período de tempo. E definitivamente esse impulso irresistível de toque-toque é a sensação mais importante de todas. Tocar na superfície nos dá uma sensação de ação real, de controle. Como seria, em vez de clicar em um ponto particular, ensinarmos nossos usuários a interagir com toda a superfície?

Vamos ver como o Instagram faz isso:


Navegação na história do Instagram

Você já viu um botão que permite navegar na História do Instagram e voltar para a história anterior? Provavelmente não, porque tudo que você precisa fazer é tocar a margem esquerda da tela para que isso aconteça.

Os usuários passaram a esperar novas formas de interagir com nossos produtos digitais e muitas vezes não envolve um botão. Os cartões são sensíveis em todas as suas superfícies; clicando em qualquer palavra, esperamos encontrar sua definição; Ao tocar imagens, esperamos alguma ação. Os usuários já estão acostumados com o fato de que áreas inteiras respondam ao toque.

Reconhecimento de Gesto

Nós entendemos os gestos muito bem porque eles são naturais para nós e refletidos em nossas ações físicas. Atualmente, quase todas as aplicações os usam para acelerar a navegação; podemos dobrar uma foto em vez de pressioná-la como um botão; podemos deslizar para navegar na galeria; ou tocar para ampliar qualquer conteúdo.


Virgil Pana


Interfaces de usuário por Ramotion & Jarek Berecki

Nós fazemos gestos não só em telas planas - gestos também são realizados em espaços AR e VR, onde podemos navegar com todo o nosso corpo.


Gestos em HoloLens pela Microsoft


Clay VR Gesture Recognition On iPhone

Interfaces de voz

Siri, Cortana, Alexa e o Assistente do Google estão funcionando. Muitos argumentam que as interfaces de voz são o futuro - é difícil discordar porque seus usos potenciais são além da conta. Podemos controlar veículos, edifícios inteligentes e máquinas simplesmente falando com eles - assim como conversamos com uma pessoa real. Com a inteligência artificial e a aprendizagem de máquinas, as máquinas agora são capazes de entender nosso idioma de forma cada vez mais precisa. Já não nos limitamos a pronunciar com cuidado "palavras mágicas"; podemos falar frases completas.


Ok, Google ...

Ao usar a fala, podemos nos mover livremente para o mundo das transferências bancárias. Atualmente, o Siri permite que você transfira dinheiro via PayPal para outra pessoa usando apenas um pedido rápido: "Siri, envie $200 para XYZ usando o PayPal." Sem botões - a única confirmação e verificação de segurança necessárias é o Touch ID.



Ações físicas, dispositivos conectados e reconhecimento de vídeo

Sorria para pagar? Está aqui! Alibaba e KFC lançaram em conjunto um sistema que permite que você pague simplesmente sorrindo para a câmera - sem botões para pressionar. O sistema funciona no reconhecimento facial e agora está disponível na China.



Este é apenas um dos potenciais usos. Nossos dispositivos já estão equipados com uma série de sensores e podem monitorar todo o seu corpo. Nada está impedindo que você use um dedo para executar qualquer ação em seu smartphone.



Outro exemplo de uma ação física que acelerará o desaparecimento dos botões é simplesmente estar perto do dispositivo. Vejamos o iWatch, por exemplo - apenas emparelhe com seu laptop para desbloquear o seu MacBook. Os dispositivos vestíveis ​​podem ser usados ​​para confirmar nossa identidade, bem como prever de maneira inteligente nossas necessidades com base na localização e nos dados dos sensores. Graças a eles, já podemos evitar o uso de botões em muitas interfaces.



Não esqueçamos sobre as tecnologias amplamente disponíveis há vários anos. Um deles é o giroscópio disponível em quase todos os smartphones, mas raramente usado em interfaces. Acima, você pode ver as interfaces experimentais criadas por Patryk Adaś.

UI Designers do futuro

Com tantas opções diferentes disponíveis para nós, agora é possível esquecer o uso de botões retangulares típicos para os usuários interagirem. Com a tecnologia de hoje, temos a capacidade de criar interfaces completamente novas que podem:

  • Economizar tempo do usuário
  • Impedir erros e
  • Compensar quaisquer ações acidentais



Interfaces conceituais de Cosmin Capitan e Ramotion

O tempo chegou - a tecnologia está nos ultrapassando. Nós, os designers, DEVEMOS perseguí-la... e certifique-se de recuperar o atraso!

POR WOJCIECH DOBRY - TOPTAL FREELANCE DESIGNER E DESIGN BLOG EDITOR @ TOPTAL
ARTIGO ORIGINAL: El Futuro del Diseño UI Sin Botones

terça-feira, 26 de setembro de 2017

CRM-GT - Consumo de Web Api usando Javascript

Este artigo tem como objetivo documentar o uso de um importante recurso do meu sistema de gerenciamento com o cliente, o CRM-GT. Este recurso se chama Web Api, e serve como um [conector] entre o sistema CRMGT e qualquer sistema legado.

Esta é a URL principal de consumo REST: /api/CRMGT/QueryXML

Com este conector, você pode efetuar todo CRUD de operações. Portanto, segue abaixo o uso prático deste recurso, usando Javascript/JQuery.

Pontos importantes:
- Não usamos a tecnologia SOAP
- Esta tecnologia exige o uso do recurso de Envelope XML para envio dos dados, e não fazemos desta forma

- Usamos REST (Desenvolvido na tecnologia ASP.NET webAPI da Microsoft, sempre com a versão mais atual do .NET)
- O que pode "confundir" alguns é o fato de passamos um [parametro no JSON] do tipo string XML, mas isto é somente mais um parâmetro da api, do tipo string, conforme veremos nos exemplos abaixo.
- Outro ponto que pode confundir é que, devido a forma de passagem dos parâmetros para nossa API, exista uma limitação do cliente para este padrão CRM-GT de envio, fazendo com que exista a necessidade de criação um pequeno desenvolvimento por parte do cliente antes do consumo da api.
- Este padrão CRM-GT de envio (ter um xml como parâmetro) torna nossa api mais segura para operações CRUD corporativas.


Para obter o Token de acesso (OAuth)
function getToken() {
	var param = {
		"orgName": "CRMGT1",
		"clientId": "+n8c++NABWZrkldVUaf0XYH2T2lG5xvUhZEVxFz46/4=__5@_",
		"clientSecret": "7RclDz1Ilbp3jyOuXJNnyfaK3bW+MIt5fU0BL1f46to=__0@_"
	};

	$.ajax({
		type: 'GET',
		url: 'https://crmgt.net/api/CRMGT/GetToken',
		data: param,
		dataType: 'json',
		async: false,
		beforeSend: function(xmlHttpRequest) {
			xmlHttpRequest.withCredentials = true;
		},
		success: function (data, textStatus, jqXHR) {
			token = data.token;
		},
		error: function (jqXHR, textStatus, errorThrown) {
			debugger;
		}
	});
}

Considerações importantes sobre o token.
- Ele expira a cada 3 horas.
- O [clientId] e o [clientSecret] são criados por Organização. O administrador da organização cria estas chaves e as disponibiliza para obtenção do Token.

Para Renovar o Token de acesso (OAuth)
function renewToken() {
    var param = {
        'orgName': 'CRMGT1',
        'clientId': '73ySJQsDnHDYugLRRYmtATjCxVmcNo2/Alz8RG9D+VQ=__5|@_11|4_13|._',
        'clientSecret': 'EPkMdqQcm0XgDxpn4lDcKKpEz0WPDQhgbXN6Nkl0JWw='
    };

    $.ajax({
        type: 'GET',
        url: 'https://crmgt.net/api/CRMGT/RenewToken',
        data: param,
        dataType: 'json',
        async: false,
        beforeSend: function (xmlHttpRequest) {
            xmlHttpRequest.withCredentials = true;
        },
        success: function (data, textStatus, jqXHR) {
            if (data == null) {
                return 0;
            } else {
                token = data.token;
            }
        },
        error: function (jqXHR, textStatus, errorThrown) {
            console.log(errorThrown);
        }
    });
}

Como saber se o token de acesso expirou? Ao executar o endpoint /GetToken, o sistema retorna um atributo informando que o tempo expirou ("expires_in" : "0").

Para os métodos de CREATE e UPDATE, no momento da configuração da tag [fields/field] atributo [type], informe os tipos correspondentes aos do [SQL SERVER].
Segue os principais:
bit
char
nchar
varchar
nvarchar
datetime
datetime2
bit
int
decimal
float
text
uniqueidentifier
Desta forma, se precisar adicionar um campo do tipo [string], informe [varchar].
Se precisar adicionar um campo do tipo [valor ou moeda], informe [decimal], e assim por diante.


Na tag [condition], atributo [operator], informe os tipos correspondentes aos do [SQL SERVER].
Segue os principais:
=
!=
<
<=
>
>=
like
like-removeformat (retira os caracteres "(", ")", "-", "espaço" e "." do campo no banco de dados)
between (coloque no atributo value o range, por ex "20200101T000000Z AND 20200131T235959Z")
in (coloque no atributo value os valores separados por vírgula, por ex "1,2,3,4")


Para efetuar um SELECT

function selectRecords() {
    var xmlSELECT = 
	"<select>" +
		"<organization name='CRMGT1' />" +
		"<table name='User' alias='tb1' />" +
		"<fields>" +
		"	<field name='tb1.UserId' label='ID' />" +
		"	<field name='tb1.Name' />" +
		"	<field name='tb1.Email' />" +
		"	<field name='tb2.Name' />" +
		"	<field name='tb3.Name' />" +
		"</fields>" +
		"<join isLeftJoin='false' name='Status' alias='tb2' fieldFrom='tb1.statuscode' fieldTo='tb2.statuscode'>" +
		"	<filter type='and'>" +
		"		<condition field='tb2.name' operator='=' value='Ativo' />" +
		"	</filter>" +
		"</join>" +
		"<join isLeftJoin='true' name='salesorder' alias='tb3' fieldFrom='tb1.userid' fieldTo='tb3.ownerid'>" +
		"	<filter type='and'>" +
		"		<condition field='tb3.name' operator='like' value='%ped%' />" +
		"	</filter>" +
		"</join>" +
		"<filter type='and'>" +
		"	<condition field='tb1.name' operator='like' value='%usr%' />" +
		"</filter>" +
		"<order>" +
		"	<field name='tb1.Name ASC'/>" +
		"	<field name='tb1.Email DESC'/>" +
		"</order>" +
	"</select>";

    var param = {
        "Type": "GET",
        "xmlContent": xmlSELECT
    };

    $.ajax({
        type: 'POST',
        url: "https://crmgt.net/api/CRMGT/QueryXML",
        data: param,
        dataType: 'json',
        contentType: "application/x-www-form-urlencoded; charset=utf-8",
        beforeSend: function (xhr) {
            xhr.setRequestHeader("Authorization", "Bearer " + token);
        },
        success: function (data, textStatus, jqXHR) {
            if (textStatus == "success") {
                // JSON que representa os [registros] retornados
                var json = JSON.parse(data.Result);
            }
        },
        error: function (jqXHR, textStatus, errorThrown) {
            debugger;
        }
    });
}

Se precisar retornar todos os campos, deixe a tag [fields] vazia **
<fields />
** Limitação: este recurso só vai funcionar se estiver buscando dados de uma única tabela.

Se precisar buscar dados NULOS (ou não nulos), utilize:
<condition field='tb1.name' operator='NULL' />
<condition field='tb1.name' operator='NOTNULL' />


Para efetuar um CREATE

function createRecord() {
    var xmlINSERT =
        "<insert>" +
        "<organization name='CRMGT1' />" +
        "<table name='account' isNN='false' setInternalFields='true' setWorkflowTrigger='false' workflowTriggerSyncMode='false' />" +
        "<records>" +
        "    <record>" +
        "        <fields>" +
        "            <field name='accountid' type='uniqueidentifier' value='NEWID' />" +
        "            <field name='name' type='varchar' value='Create sample 1...' />" +
        "            <field name='AccountNumber' type='varchar' value='1' />" +
        "            <field name='ownerid' type='uniqueidentifier' lookuptable='user' lookupsearchfield='name' value='system' />" +
        "        </fields>" +
        "    </record>" +
        "    <record>" +
        "        <fields>" +
        "            <field name='accountid' type='uniqueidentifier' value='NEWID' />" +
        "            <field name='name' type='varchar' value='Create sample 2...' />" +
        "            <field name='AccountNumber' type='varchar' value='2' />" +
        "        </fields>" +
        "    </record>" +
        "</records>" +
        "</insert>";

    var param = {
        "Type": "SET",
        "xmlContent": xmlINSERT
    };

    $.ajax({
        type: 'POST',
        url: "https://crmgt.net/api/CRMGT/QueryXML",        
        data: param,
        dataType: 'json',
        contentType: "application/x-www-form-urlencoded; charset=utf-8",
        beforeSend: function (xhr) {
            xhr.setRequestHeader("Authorization", "Bearer " + token);
        },
        success: function (data, textStatus, jqXHR) {
        },
        error: function (jqXHR, textStatus, errorThrown) {
        }
    });
}

[C.1] - Note a forma de configuração para inserir um valor no campo [ownerid].
Por ser um campo do tipo uniqueidentifier (ou GUID) no banco de dados, podemos passar como valor (para o atributo [value]) dois conteudos:

- o GUID diretamente
- Um texto para busca do GUID

Tomando o exemplo acima temos o atributo [lookuptable] preenchido como 'user', o atributo [lookupsearchfield] como 'name' e por fim o atributo [value] como 'system'.

Isto diz o seguinte para o sistema: faça um select na tabela 'user' onde o campo 'name' seja igual a 'system', depois retorne o GUID da 'user'.


Se precisar definir uma regra antes da criação dos registros, você pode adicionar a seguinte tag [rules] depois da tag [table]:
<rules>
	<rule action="insert_ignoreifexists" actionoperator="AND">
		<fields>
			<field name="protocol" type="VarChar" />
			<field name="incidentNumber" type="Int" />
			<field name="ownerid" type="UniqueIdentifier" lookuptable="user" lookupsearchfield="name" />
			<field name="modifiedon" type="datetime" hourformat="HH:mm" />
		</fields>
	</rule>
</rules>

Desta forma, através da regra [insert_ignoreifexists] você não permite a inclusão do registro se os campos especificados na tag [fields] existirem na tabela.
Mas se você quiser [atualizar] o registro se ele for encontrado, use a regra [insert_updateifexists]. Para esta regra, o update será realizado usando na cláusula [where] a [chave primária] da tabela.

Para campos do tipo [lookup] na regra você pode usar os atributos [lookuptable] e [lookupsearchfield] somente se o campo especificado na regra, no exemplo acima o [ownerid], tiver no XML de INSERT o conteúdo diferente de um GUID.
[lookuptable] - deve contér o nome da tabela que você deseja procurar o valor (no exemplo temos a tabela User)
[lookupsearchfield] - deve contér o nome do campo (da tabela [lookuptable]) para procurar o valor especificado no XML de INSERT.

Regras para campos do tipo [DateTime] vc pode especificar o formato da Hora para ser comparada.
Adicione o atributo [hourformat] com os seguintes conteúdos válidos:
HH:mm
HH:mm:ss
No exemplo acima temos uma regra para o campo [modifiedOn] com o atributo hourformat="HH:mm".

Formato de Campo Data
Sempre que passar um valor de data, passar no seguinte formato:


yyyyMMddTHHmmssZ


Exemplo: 20230616T095600Z


Se precisar [atualizar] o campo no CRM com valor Nulo:
<field name='dtFieldName' type='datetime' value='NULL' />


Se precisar [atualizar] o campo no CRM com a data [corrente]:
<field name='dtFieldName' type='datetime' value='GETDATE' />


Formato de Campo Decimal
Sempre que passar um valor decimal, usar o formato americano, somente com o separador de centavos:


Ex: 1234.56



Formato HTML
Sempre que passar uma string com conteúdo HTML, passe no formato ENCODE.

Exemplo: Preciso passar uma string html, onde em determinados pontos precisa ter uma quebra de linha.
No formato html, para quebras, usamos, por ex <br>.
Como passar esta tag br no formato Encode?
Desta forma: &lt;br&gt;
Onde:
&lt; -> representa o símbolo "<"
br -> comando de quebra
&gt; -> representa o símbolo ">"

Exemplo da tag <field> com html no [value]:
<field name='description' type='nvarchar' decodestring='true' value='123&lt;br&gt;456'/>

Não esqueça do atributo decodestring='true' para que a api efetue o tratamento de [decode] corretamente.



Para efetuar um UPDATE

function updateRecord() {
    var xmlUPDATE =
       "<update>" +
       " <organization name='CRMGT1' />" +
       " <table name='account' setWorkflowTrigger='false' />" +
       " <set>" +
       "  <field name='name' type='varchar' setWorkflowFieldTrigger='false' value='UPDATED - Create sample 1...' />" +
       "  <field name='modifiedOn' type='datetime' value='GETDATE' />" +
       " </set>" +
       " <filter type='and'>" +
       "  <condition field='name' operator='=' value='Create sample 1...' />" +
       " </filter>" +
       "</update>";

    var param = {
       "Type": "SET",
       "xmlContent": xmlUPDATE
    };

    $.ajax({
        type: 'POST',
        url: "https://crmgt.net/api/CRMGT/QueryXML",        
        data: param,
        dataType: 'json',
        contentType: "application/x-www-form-urlencoded; charset=utf-8",
        beforeSend: function (xhr) {
            xhr.setRequestHeader("Authorization", "Bearer " + token);
        },
        success: function (data, textStatus, jqXHR) {
        },
        error: function (jqXHR, textStatus, errorThrown) {
        }
    });
}

Para atualizar um campo do tipo [lookUp], vale a mesma regra especificada no item [C.1] deste documento.

Para efetuar um DELETE

function deleteRecord() {
    var xmlDELETE =
        "<delete>" +
        " <organization name='CRMGT1' />" +
        " <table name='account' setWorkflowTrigger='false' />" +
        " <filter type='and'>" +
        "  <condition field='name' operator='like' value='%Create sample%' />" +
        " </filter>" +
        "</delete>";

    var param = {
        "Type": "SET",
        "xmlContent": xmlDELETE
    };

    $.ajax({
        type: 'POST',
        url: "https://crmgt.net/api/CRMGT/QueryXML",        
        data: param,
        dataType: 'json',
        contentType: "application/x-www-form-urlencoded; charset=utf-8",
        beforeSend: function (xhr) {
            xhr.setRequestHeader("Authorization", "Bearer " + token);
        },
        success: function (data, textStatus, jqXHR) {
        },
        error: function (jqXHR, textStatus, errorThrown) {
        }
    });
}

Para executar uma [QUERY EXEC]

function executeQE() {
    var xmlQE =
	"<queryexec>" +
	" <organization name='CRMGT1' />" +
	" <queryexecid value='buscarocorrencia' />" +
	" <paramset>" +
	"	<param name='@_id_' type='uniqueidentifier' value='62a9a715-8574-4813-a69f-e732c76313e0' />" +
	" </paramset>" +
	"<filter type='and'>" +
	"	<condition field='inc.StatusCode' operator='=' value='1' />" +
	"</filter>" +
	"</queryexec>";

    var param = {
        "Type": "QueryExec",
        "xmlContent": xmlQE
    };

    $.ajax({
        type: 'POST',
        url: "https://crmgt.net/api/CRMGT/QueryXML",        
        data: param,
        dataType: 'json',
        contentType: "application/x-www-form-urlencoded; charset=utf-8",
        beforeSend: function (xhr) {
            xhr.setRequestHeader("Authorization", "Bearer " + token);
        },
        success: function (data, textStatus, jqXHR) {
        },
        error: function (jqXHR, textStatus, errorThrown) {
        }
    });
}

Obs: As tags <paramset> e <filter> são [opcionais]. Elas são úteis quando precisar passar mais parâmetros de filtro para a Query Exec criada no sistema ou para substituir o valor das macros do sistema (@_id_ por exemplo).

CRM-GT - Consumo de Web Api usando C#

Este artigo tem como objetivo documentar o uso de um importante recurso do meu sistema de gerenciamento com o cliente, o CRM-GT. Este recurso se chama Web Api, e serve como um [conector] entre o sistema CRMGT e qualquer sistema legado.

Esta é a URL principal de consumo REST: /api/CRMGT/QueryXML

Com este conector, você pode efetuar todo CRUD de operações. Portanto, segue abaixo o uso prático deste recurso, usando C#.

Pontos importantes:
- Não usamos a tecnologia SOAP
- Esta tecnologia exige o uso do recurso de Envelope XML para envio dos dados, e não fazemos desta forma

- Usamos REST (Desenvolvido na tecnologia ASP.NET webAPI da Microsoft, sempre com a versão mais atual do .NET)
- O que pode "confundir" alguns é o fato de passamos um [parametro no JSON] do tipo string XML, mas isto é somente mais um parâmetro da api, do tipo string, conforme veremos nos exemplos abaixo.
- Outro ponto que pode confundir é que, devido a forma de passagem dos parâmetros para nossa API, exista uma limitação do cliente para este padrão CRM-GT de envio, fazendo com que exista a necessidade de criação um pequeno desenvolvimento por parte do cliente antes do consumo da api.
- Este padrão CRM-GT de envio (ter um xml como parâmetro) torna nossa api mais segura para operações CRUD corporativas.

Busca do Token de acesso (OAuth)
var url = "https://crmgt.net/api/CRMGT/GetToken";
url += "?orgName=CRMGT1";
url += "&clientId=+n8c++NABWZrkldVUaf0XYH2T2lG5xvUhZEVxFz46/4=__5@_";
url += "&clientSecret=7RclDz1Ilbp3jyOuXJNnyfaK3bW+MIt5fU0BL1f46to=__0@_";
var jToken = GetString(url);
var token = JsonConvert.DeserializeObject<JObject>(jToken).SelectToken("token").ToString();

Considerações importantes sobre o token.
- Ele expira a cada 3 horas.
- O [clientId] e o [clientSecret] são criados por Organização. O administrador da organização cria estas chaves e as disponibiliza para obtenção do Token.

Para Renovar o Token de acesso (OAuth)
var url = "https://crmgt.net/api/CRMGT/RenewToken";
url += "?orgName=CRMGT1";
url += "&clientId=+n8c++NABWZrkldVUaf0XYH2T2lG5xvUhZEVxFz46/4=__5@_";
url += "&clientSecret=7RclDz1Ilbp3jyOuXJNnyfaK3bW+MIt5fU0BL1f46to=__0@_";
var jToken = GetString(url);
var token = JsonConvert.DeserializeObject<JObject>(jToken).SelectToken("token").ToString();

Como saber se o token de acesso expirou? Ao executar o endpoint /GetToken, o sistema retorna um atributo informando que o tempo expirou ("expires_in" : "0").


Para os métodos de CREATE e UPDATE, no momento da configuração da tag [fields/field] atributo [type], informe os tipos correspondentes aos do [SQL SERVER].
Segue os principais:
char
nchar
varchar
nvarchar
datetime
datetime2
bit
int
decimal
float
text
uniqueidentifier
Desta forma, se precisar adicionar um campo do tipo [string], informe [varchar].
Se precisar adicionar um campo do tipo [valor ou moeda], informe [decimal], e assim por diante.


Na tag [condition], atributo [operator], informe os tipos correspondentes aos do [SQL SERVER].
Segue os principais:
=
!=
<
<=
>
>=
like
like-removeformat (retira os caracteres "(", ")", "-", "espaço" e "." do campo no banco de dados)
between (coloque no atributo value o range, por ex "20200101T000000Z AND 20200131T235959Z")
in (coloque no atributo value os valores separados por vírgula, por ex "1,2,3,4")


Para efetuar um SELECT

1 - Monte o "SELECT" através de uma instrução XML:
string xmlSELECT = @"
<select>
	<organization name='{0}' />
	<table name='User' alias='tb1' />
	<fields>
		<field name='tb1.UserId' label='ID' />
		<field name='tb1.Name' />
		<field name='tb1.Email' />
		<field name='tb2.Name' />
		<field name='tb3.Name' />
	</fields>
	<join isLeftJoin='false' name='Status' alias='tb2' fieldFrom='tb1.statuscode' fieldTo='tb2.statuscode'>
		<filter type='and'>
			<condition field='tb2.name' operator='=' value='Ativo' />
		</filter>                     
	</join>
	<join isLeftJoin='true' name='salesorder' alias='tb3' fieldFrom='tb1.userid' fieldTo='tb3.ownerid'>
		<filter type='and'>
			<condition field='tb3.name' operator='like' value='%ped%' />
		</filter>                     
	</join>
	<filter type='and'>
		<condition field='tb1.name' operator='like' value='%usr%' />
	</filter>
	<order>
		<field name='tb1.Name ASC'/>
		<field name='tb1.Email DESC'/>
	</order>	
</select>";

Se precisar retornar todos os campos, deixe a tag [fields] vazia **
<fields />
** Limitação: este recurso só vai funcionar se estiver buscando dados de uma única tabela.

Se precisar buscar dados NULOS (ou não nulos), utilize:
<condition field='tb1.name' operator='NULL' />
<condition field='tb1.name' operator='NOTNULL' />


O XML acima é a representação do SELECT-SQL abaixo:
SELECT tb1.UserId, tb1.Name, tb1.Email, tb2.Name, tb3.Name
FROM [User] tb1 
JOIN [Status] tb2 ON tb1.statuscode = tb2.statuscode AND tb2.name = 'Ativo'
LEFT JOIN [salesorder] tb3 ON TB1.UserId = tb3.ownerid AND tb3.name like '%ped%'
WHERE tb1.Name like '%usr%'
ORDER BY tb1.Name ASC, tb1.Email DESC

2 - Passe como parâmetro a informação de [Organização], conforme a sequência abaixo.
var xmlF = string.Format(xmlSELECT, "CRMGT1");

3 - Execute a instrução, chamando a Web Api:
var header = new Dictionary<string, object>();
header.Add("Authorization", $"Bearer {token}");

var content = new Dictionary<string, object>();
content.Add("Type", "GET");
content.Add("Caller", "My Function Caller Name");
content.Add("xmlContent", xmlF);

var result = ExecutePostAsync("https://crmgt.net/api/CRMGT/QueryXML", content, header);

Segue abaixo métodos [GetString] e [ExecutePostAsync] que efetuam chamadas HTTP:
public static String GetString(String url)
{
   var urlContents = "";
   try
   {
      using (HttpClient client = new HttpClient())
      {
         urlContents = client.GetStringAsync(new Uri(url)).Result;
      }
   }
   catch (Exception ex)
   {
   }

   return urlContents;
}

public static string ExecutePostAsync(string url, Dictionary<string, object> content, Dictionary<string, object> headerList = null) {
	string result = "";

	try {
		using (HttpClient client = new HttpClient()) {
			if (headerList != null) {
				foreach (var item in headerList) {
					client.DefaultRequestHeaders.Add(item.Key, item.Value.ToString());
				}
			}

			if (content != null) {
				var multiPartContent = new MultipartFormDataContent();
				foreach (var item in content) {
					multiPartContent.Add(new StringContent(item.Value.ToString()), string.Format("\"{0}\"", item.Key));
				}

				var request = new HttpRequestMessage(HttpMethod.Post, url);
				request.Content = multiPartContent;
				result = client.SendAsync(request).Result.Content.ReadAsStringAsync().Result;
			}
		}
	}
	catch (Exception ex) {
	}

	return result;
}




Para efetuar um CREATE

1 - Monte o "CREATE" através de uma instrução XML:
string xmlINSERT = @"
    <insert>
        <organization name='{0}' />
        <table name='{1}' isNN='false' setInternalFields='true' setWorkflowTrigger='false' workflowTriggerSyncMode='false' />
        <records>
            <record>
                <fields>
                    <field name='statuscode' type='int' value='998' />
                    <field name='name' type='varchar' value='test1...' />
                    <field name='ownerid' type='uniqueidentifier' lookuptable='user' lookupsearchfield='name' value='system' />
                </fields>
            </record>
            <record>
                <fields>
                    <field name='statuscode' type='int' value='999' />
                    <field name='name' type='varchar' value='test2...' />
                    <field name='ownerid' type='uniqueidentifier' value='9EC0ABA8-2947-4857-9698-1C43BBBFAB5B' />
                </fields>
            </record>
        </records>
    </insert>";

2 - Passe como parâmetro as informações de [Organização] e [tabela], conforme a sequência abaixo.
var xmlF = string.Format(xmlINSERT, "CRMGT1", "lead");

3 - Execute a instrução, chamando a Web Api:
var header = new Dictionary<string, object>();
header.Add("Authorization", $"Bearer {token}");

var content = new Dictionary<string, object>();
content.Add("Type", "SET");
content.Add("Caller", "My Function Caller Name");
content.Add("xmlContent", xmlF);

var result = ExecutePostAsync("https://crmgt.net/api/CRMGT/QueryXML", content, header);

[C.4] - Note a forma de configuração para inserir um valor no campo [ownerid].
Por ser um campo do tipo uniqueidentifier (ou GUID) no banco de dados, podemos passar como valor (para o atributo [value]) dois conteudos:

- o GUID diretamente
- Um texto para busca do GUID

Tomando o exemplo acima temos o atributo [lookuptable] preenchido como 'user', o atributo [lookupsearchfield] como 'name' e por fim o atributo [value] como 'system'.

Isto diz o seguinte para o sistema: faça um select na tabela 'user' onde o campo 'name' seja igual a 'system', depois retorne o GUID da 'user'.


Para inserir dados em uma tabela N-N, adicione o atributo [isNN='true'] na tag xml [table], conforme exemplificado abaixo:
string xmlINSERT = @"
    <insert>
        <organization name='{0}' />
        <table name='{1}' isNN='true' />
        <records>
            <record>
                <fields>
                    <field name='pricelist_productid' type='uniqueidentifier' value='NEWID' />
                    <field name='pricelistid' type='uniqueidentifier' value='3BEF33F8-A159-4F77-964D-B820B8414E59' />
                    <field name='productid' type='uniqueidentifier' value='B091A317-4FF7-42BE-AD86-D77C22059E49' />
                </fields>
            </record>
            <record>
                <fields>
                    <field name='pricelist_productid' type='uniqueidentifier' value='NEWID' />
                    <field name='pricelistid' type='uniqueidentifier' value='3BEF33F8-A159-4F77-964D-B820B8414E59' />
                    <field name='productid' type='uniqueidentifier' value='6922B778-B4FF-4564-A992-E40A020C599F' />
                </fields>
            </record>
        </records>
    </insert>";

Se precisar definir uma regra antes da criação dos registros, você pode adicionar a seguinte tag [rules] depois da tag [table]:
<rules>
	<rule action="insert_ignoreifexists" actionoperator="AND">
		<fields>
			<field name="protocol" type="VarChar" />
			<field name="incidentNumber" type="Int" />
			<field name="ownerid" type="UniqueIdentifier" lookuptable="user" lookupsearchfield="name" />
			<field name="modifiedon" type="datetime" hourformat="HH:mm" />
		</fields>
	</rule>
</rules>

Desta forma, através da regra [insert_ignoreifexists] você não permite a inclusão do registro se os campos especificados na tag [fields] existirem na tabela.
Mas se você quiser [atualizar] o registro se ele for encontrado, use a regra [insert_updateifexists]. Para esta regra, o update será realizado usando na cláusula [where] a [chave primária] da tabela.

Para campos do tipo [lookup] na regra você pode usar os atributos [lookuptable] e [lookupsearchfield] somente se o campo especificado na regra, no exemplo acima o [ownerid], tiver no XML de INSERT o conteúdo diferente de um GUID.
[lookuptable] - deve contér o nome da tabela que você deseja procurar o valor (no exemplo temos a tabela User)
[lookupsearchfield] - deve contér o nome do campo (da tabela [lookuptable]) para procurar o valor especificado no XML de INSERT.

Regras para campos do tipo [DateTime] vc pode especificar o formato da Hora para ser comparada.
Adicione o atributo [hourformat] com os seguintes conteúdos válidos:
HH:mm
HH:mm:ss
No exemplo acima temos uma regra para o campo [modifiedOn] com o atributo hourformat="HH:mm".

Formato de Campo Data
Sempre que passar um valor de data, passar no seguinte formato:


yyyyMMddTHHmmssZ


Exemplo: 20230616T095600Z


Se precisar [atualizar] o campo no CRM com valor Nulo:
<field name='dtFieldName' type='datetime' value='NULL' />


Se precisar [atualizar] o campo no CRM com a data [corrente]:
<field name='dtFieldName' type='datetime' value='GETDATE' />


Formato de Campo Decimal
Sempre que passar um valor decimal, usar o formato americano, somente com o separador de centavos:


Ex: 1234.56



Formato HTML
Sempre que passar uma string com conteúdo HTML, passe no formato ENCODE.

Exemplo: Preciso passar uma string html, onde em determinados pontos precisa ter uma quebra de linha.
No formato html, para quebras, usamos, por ex <br>.
Como passar esta tag br no formato Encode?
Desta forma: &lt;br&gt;
Onde:
&lt; -> representa o símbolo "<"
br -> comando de quebra
&gt; -> representa o símbolo ">"

Exemplo da tag <field> com html no [value]:
<field name='description' type='nvarchar' decodestring='true' value='123&lt;br&gt;456'/>

Não esqueça do atributo decodestring='true' para que a api efetue o tratamento de [decode] corretamente.



Para efetuar um UPDATE

1 - Monte o "UPDATE" através de uma instrução XML:
string xmlUPDATE = @"
    <update>
        <organization name='{0}' />
        <table name='{1}' setWorkflowTrigger='false' />
        <set>
            <field name='name' type='varchar' setWorkflowFieldTrigger='false' value='TEST UPD...' />
            <field name='modifiedOn' type='datetime' value='GETDATE' />
        </set>
        <filter type='and'>
            <condition field='name' operator='=' value='TEST' />
        </filter>
    </update>";

2 - Passe como parâmetro as informações de [Organização] e [tabela], conforme a sequência abaixo.
var xmlF = string.Format(xmlUPDATE, "CRMGT1", "Status");

3 - Execute a instrução, chamando a Web Api:
var header = new Dictionary<string, object>();
header.Add("Authorization", $"Bearer {token}");

var content = new Dictionary<string, object>();
content.Add("Type", "SET");
content.Add("Caller", "My Function Caller Name");
content.Add("xmlContent", xmlF);

var result = ExecutePostAsync("https://crmgt.net/api/CRMGT/QueryXML", content, header);

Para atualizar um campo do tipo [lookUp], vale a mesma regra especificada no item [C.4] deste documento.

Para efetuar um DELETE

1 - Monte o "DELETE" através de uma instrução XML:
string xmlDELETE = @"
    <delete>
        <organization name='{0}' />
        <table name='{1}' setWorkflowTrigger='false' />
        <filter type='and'>
            <condition field='name' operator='=' value='TEST...' />
        </filter>
    </delete>";

2 - Passe como parâmetro as informações de [Organização] e [tabela], conforme a sequência abaixo.
var xmlF = string.Format(xmlDELETE, "CRMGT1", "Status");

3 - Execute a instrução, chamado a Web Api:
var header = new Dictionary<string, object>();
header.Add("Authorization", $"Bearer {token}");

var content = new Dictionary<string, object>();
content.Add("Type", "SET");
content.Add("Caller", "My Function Caller Name");
content.Add("xmlContent", xmlF);

var result = ExecutePostAsync("https://crmgt.net/api/CRMGT/QueryXML", content, header);


Para executar uma [QUERY EXEC]

1 - Monte a "QUERY EXEC" através de uma instrução XML:
string xmlQE = @"
	<queryexec>
	<organization name='{0}' />
	<queryexecid value='{1}' />
	<paramset>
		<param name='@_id_' type='uniqueidentifier' value='62a9a715-8574-4813-a69f-e732c76313e0' />
	</paramset>
	<filter type='and'>
		<condition field='inc.StatusCode' operator='=' value='1' />
	</filter>
	</queryexec>";

2 - Passe como parâmetro as informações de [Organização] e [ID da query exec], conforme a sequência abaixo.
var xmlF = string.Format(xmlQE, "CRMGT1", "buscarocorrencias");

3 - Execute a instrução, chamado a Web Api:
var header = new Dictionary<string, object>();
header.Add("Authorization", $"Bearer {token}");

var content = new Dictionary<string, object>();
content.Add("Type", "QueryExec");
content.Add("Caller", "My Function Caller Name");
content.Add("xmlContent", xmlF);

var result = ExecutePostAsync("https://crmgt.net/api/CRMGT/QueryXML", content, header);

Obs: As tags <paramset> e <filter> são [opcionais]. Elas são úteis quando precisar passar mais parâmetros de filtro para a Query Exec criada no sistema ou para substituir o valor das macros do sistema (@_id_ por exemplo).