Teste de integração do LIS 2.0

Testar a integração LIS de uma perspectiva funcional, antes de conectar o SIA à integração, permite que você confirme o funcionamento adequado da configuração na metade da integração Learn. Depois de ter certeza de que o Learn está lidando adequadamente com as solicitações do LIS, ao se conectar ao seu Sistema de informações do aluno (SIA), você eliminou metade da equação caso ocorram problemas de conectividade ou operação inadequada. Depois de testar usando os exemplos fornecidos, você pode considerar extrair a saída do LIS do Sistema de informações do aluno (SIA) e complementar o teste não conectado antes de continuar conectando o Sistema de informações do aluno (SIA) ao Learn – novamente limitando o número de variáveis no cenário de teste.

As integrações LIS são baseadas no serviço da web e usam o SOAP como o transporte de dados. O SOAP é um protocolo baseado em formato de mensagem XML que permite a troca de informações estruturadas.

Há dois meios de colocar dados no Learn usando dados formatados em LIS: você pode usar os terminais do serviço web ou fazer upload de arquivos XML.

Depois de configurar a integração LIS, você precisará observar os terminais do serviço da web – eles serão usados na configuração do ambiente de teste. Os terminais para integração LIS são detectáveis usando o link Web Service Information em uma integração LIS configurada.

Além disso, você precisará anotar o nome de usuário e senha que você inseriu para a integração – eles podem ser descobertos selecionando a opção Editar no menu da integração.

Testar os serviços da web requer o uso de uma ferramenta que seja capaz de publicar mensagens SOAP nos terminais do serviço da web. Os exemplos a seguir usam uma ferramenta chamada SoapUI. O SoapUI está disponível em www.soapui.org. O SoapUI é uma solução de teste funcional de plataforma cruzada livre e de código aberto que permite que você crie e execute, de forma fácil e rápida, testes funcionais e de carga do serviço da web.

Depois de concluir o teste de uso da integração LIS, você pode configurar o SIA para enviar os dados aos terminais de acordo com a operação necessária. (veja exemplos de serviço).

Cada serviço testado exigirá um WSDL para a construção dos métodos suportados. O URL de WSDL é o valor "URL de terminal" para o gerenciamento em "Web Services locais do Learn", concatenado com ".wsdl". O URL de WSDL construído terá uma aparência semelhante à seguinte:

https://<yourserver>/webapps/bb-data-integration-lis-BBLEARN/services/PersonManagementServiceSyncService .wsdl

Você construirá quatro desses, um para cada serviço a ser testado:

CourseSectionManagerSyncService

GroupManagementSyncService

MembershipManagementSyncService

PersonManagementSyncService

dataSetStatus não é um serviço LIS, mas sim um serviço fornecido pelo Learn para monitorar a atividade de integração.

Algumas instalações do SoapUI podem gerar um erro "org.apache.xmlbeans.XmlException: java.io.CharConversionException: Caracteres maiores que 4 bytes não são suportados: byte 0x96 implica um comprimento de mais de 4 bytes" ao tentar carregar o WSDL.

Para resolver esse erro:

Essa informação é usada para todos os serviços do projeto. O nome de usuário e a senha fornecem as informações de autenticação necessárias para identificar a integração de destino e acessar os serviços.

Para criar projetos para Curso, Associação e Grupo, você precisará repetir as etapas 1 a 5 acima. Embora o SoapUI suporte vários WSDLs por projeto, é mais fácil manter os serviços separados se quatro projetos forem criados.

O SoapUI gera modelos de solicitação com base nos WSDLs fornecidos que, embora úteis para entender o formato dos objetos gerenciados do LIS, não são adequados para enviar ao Learn. Isso não causará um problema; o Learn simplesmente retornará um erro para o processo.

Para testar, um conjunto de dados compatível deve ser enviado. Os exemplos fornecidos abaixo podem ser usados para realizar os testes iniciais, após os quais os extratos reais do SIA podem ser usados.

As implementações do Blackboard Learn 9.1 SP 14 e anteriores do LIS oferecem suporte apenas a serviços de substituição – você pode verificar os serviços compatíveis enviando os modelos de solicitação gerados. Os serviços sem suporte responderão com um erro sem suporte.

Observe o ícone circulado na imagem acima – isso habilita a versão com guias do visualizador.

Repita as etapas 1 a 5 para os demais projetos/interfaces, usando os arquivos de amostra fornecidos – isso garante que não haja problemas na configuração da integração antes de testar com dados "reais" ou se conectar ao SIA. Além disso, você pode usar esse processo para testar conjuntos de dados extraídos ou construídos à mão.

O Learn Sistema de informações do aluno (SIA) Framework permite o upload de XML formatado em massa por meio da interface do usuário. Esta demonstração explica as diferenças entre os arquivos em massa e o formato de evento fornecido pelo SIA aos terminais do LIS.

Quando um SIA (Sistema de informações do aluno) compatível com LIS se comunica com o Learn, o SIA envia uma mensagem SOAP completamente formada para os terminais do serviço da web. Essa mensagem SOAP contém um wrapper em torno dos dados XML do LIS. Essa informação não é necessária para fazer um upload manual e causará um erro de feed se for incluída. Uma amostra truncada para um objeto Pessoa (Usuário) é mostrada abaixo, no Conjunto de dados 1.0. Para obter uma descrição completa do formato de dados para cada objeto suportado, consulte Formato de dados do LIS 2.0.

<?xml version='1.0' encoding='ISO-8859-1'?>
<bulkDataRecord xmlns="http://www.imsglobal.org/services/li...sDataFile_v1p0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.imsglobal.org/services/li...sDataFile_v1p0 ../schemas/imsbdemsDataFile_v1p0.xsd">
<!-- Consider everything ABOVE this line as the "feed file header" -->
  <!-- start persons here -->
  <transactionRecord>
    <transactionOpIdentifier>identifier</transactionOpIdentifier>
    <serviceName>PersonManagementService</serviceName>
    <interfaceName>PersonManager</interfaceName>
    <operationName>replacePerson</operationName>
    <!-- Consider everything ABOVE this line as the "personRecord header";
         operationName will be replacePerson or deletePerson -->
   <parameterSet>
     <parameterRecord>
       <parameterInvoc>In</parameterInvoc>
       <parameterName>sourcedId</parameterName>
       <parameterType>GUID</parameterType>
       <parameterValue>55555</parameterValue> <!-- ID for logging -->
     </parameterRecord>
     <parameterRecord>
       <parameterInvoc>In</parameterInvoc>
       <parameterName>personRecord</parameterName>
       <parameterType>PersonRecord</parameterType>
       <parameterValue>
         <personRecord>
           <sourcedGUID>
             <refAgentInstanceID>unknown</refAgentInstanceID>
             <sourcedId>55555</sourcedId> <!-- batch_uid (for real) -->
           </sourcedGUID>
           <person> <!-- start person record -->
             <formname>
              <formnameType>
                <instanceIdentifier>
                  <language>en</language>
                  <textString>unknown</textString>
                </instanceIdentifier>
                <instanceVocabulary>
                   http://www.imsglobal.org/lis/pmsv2p0/formatnmetypevocabularyv1p0 
                <instanceVocabulary>
                <instanceValue>
                  <language>en</language>
                  <textString>Full</textString>
                </instanceValue>
              </formnameType>
              <formattedName>
                <language>en</language>
                <textString>Dr. First Middle Last, Jr.</textString> <!-- Full Name IGNORED by Learn-->
              </formattedName>
            </formname>
      ...
      </person> 
      </personRecord><!-- end person record -->
      <!-- could have more <personRecord></personRecord>s here -->
    </parameterValue>
</parameterRecord>
</parameterSet>
</transactionRecord>
<!-- could have additional transactionRecords for Courses, Memberships, or Groups here -->
</bulkDataRecord>
 <!-- Master closing tag -->

Conjunto de Dados 1.0: dados de exemplo LIS para uso em um arquivo de upload LIS da interface do Learn. O arquivo completo está disponível no conjunto de amostras para download no link abaixo.

Os arquivos de dados em massa exigem minimamente a remoção das tags de abertura e fechamento SOAP-ENV:Envelope e SOAP-ENV:Body em uma mensagem gerada pelo LIS e a substituição pelas tags de abertura e fechamento bulkDataRecord. Isso é mostrado no conjunto de dados abreviado acima. Se estiver executando várias transações (por exemplo: para pessoas, cursos e associações) em um único arquivo, elas devem ser agrupadas em tags transactionRecord adicionais (consulte o exemplo completo).

Depois de preparar os arquivos de dados, abra Carregar um arquivo de feed no menu de integração LIS.

Você será direcionado para a página de upload, na qual seleciona o arquivo para fazer upload. Para esta demonstração, selecione o arquivo de amostra fornecido: SampleBulkRequest_PersonCourseMemberTerm.xml.

Com o envio do arquivo, você será redirecionado de volta para a página da Integração. Para visualizar os resultados do teste, você pode inspecionar via UI de administração os objetos criados ou atualizados ou usar o visualizador de registrosdo SIA Framework para visualizar o registro da integração.

Para visualizar o registro da integração, selecione Exibir registro no menu da integração e você será direcionado para a página de registro da integração.

Para inspecionar mais a fundo uma mensagem registrada, selecione o item de linha da mensagem na lista e os detalhes aparecerão na área Detalhes da mensagem, abaixo da lista de mensagens.

Esses detalhes conterão informações úteis sobre o problema de depuração. Por exemplo:

<feb _x0032_0=""> Dados inválidos para atributo: função. Pulando o registro inteiro. Motivo: A função do curso é inválida.

InvalidData

Ocorreu um erro ao processar o seguinte XML:

Em

sourcedId

GUID

test_course.55555

Em

registro de associação

registro de associação

<membershipRecord><sourcedGUID><refAgentInstanceID>unknown</refAgentInstanceID><sourcedId>test_course.55555</sourcedId></sourcedGUID><membership><collectionSourcedId>test_course</collectionSourcedId><membershipIdType>courseSection</membershipIdType><member><personSourcedId>55555</personSourcedId><role><roleType>Learner</roleType><subRole>Learner</subRole><timeFrame><begin>2014-02-01T15:00:00</begin><end>2014-09-01T15:50:00</end><restrict>false</restrict><adminPeriod><language>en</language><textString>201330</textString></adminPeriod></timeFrame><status>Active</status><dateTime>2011-08-04T15:00:00</dateTime><creditHours>0</creditHours><dataSource>SIS</dataSource><extension><extensionNameVocabulary>unknown</extensionNameVocabulary><extensionTypeVocabulary>unknown</extensionTypeVocabulary><extensionField><fieldName>LIS2.0Role/Gradable</fieldName><fieldType>String</fieldType><fieldValue>Gradable</fieldValue></extensionField><extensionField><fieldName>LIS20DeliverySystem</fieldName><fieldType>String</fieldType><fieldValue>BB</fieldValue></extensionField></extension></role></member><dataSource>SIS</dataSource></membership></membershipRecord></feb>

blackboard.dataintegration.lis.operation.OperationExecutorException: InvalidData

Os detalhes da mensagem anterior indicam uma operação replaceMembership com falha, especificamente uma Função de curso incorreta (indicada pelo texto realçado em amarelo). A solicitação publicada está incluída e podemos ver que as funções são fornecidas de forma incorreta como "Aprendiz" – altere para "Aluno" e reenvie, o que resultará em uma solicitação replaceMembership bem-sucedida.

A configuração para testar as solicitações do serviço em massa é a mesma que para os outros serviços, com uma exceção – você deve fornecer um servidor de arquivos ao qual o servidor de aplicativos do Learn tenha acesso para a "captura" do arquivo de dados em massa pelo serviço LIS.

A arquitetura do serviço web do Bulk Data Exchange é composta por três partes: o cliente (neste caso, o SoapUI), a instância do LIS na instância de teste do Learn e um servidor de arquivos. O cliente envia uma mensagem SOAP para o serviço da web de Troca de dados em massa. A solicitação do cliente inclui o URL do arquivo de lote a ser processado (que está localizado no servidor de arquivos) e qual operação deve ser executada.

Baixe o arquivo SimpleHttpServer.zip vinculado abaixo e descompacte no servidor onde você colocará seus arquivos de teste.

Baixe o arquivo SampleBulkRequest_PersonCourseMemberTerm.xml e coloque-o no diretório do qual os arquivos serão entregues.

java -jar SimpleHttpServer.jar

Uso: java SimpleHttpServer <port number=""> <path to="" directory="" to="" serve="" files="" from=""> <username> <password></username></path></port>

Por exemplo:

java -jar SimpleHttpServer.jar 8081 /Usuários/moneil/Desktop/LISTEST moneil moneil

Servidor em execução na porta 8081. Pressione Ctrl-C para sair.

Acesse o servidor através do seu navegador para testar a entrega do arquivo:

Por exemplo:

http://10.0.1.16:8081/SampleBulkRequest_PersonCourseMemberTerm.xml

A configuração do SoapUI para testar a Troca de dados em massa é a mesma do que para os outros serviços do LIS.

Abra a solicitação announceBulkDataExchange e copie/cole o conteúdo do Conjunto de dados 2 abaixo na visualização da solicitação.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ims="http://www.imsglobal.org/services/li.../imsbdems_v1p0">
<soapenv:Header>
<ims:imsx_syncRequestHeaderInfo>
<ims:imsx_version>V1.0</ims:imsx_version>
<ims:imsx_messageIdentifier>123456</ims:imsx_messageIdentifier>
</ims:imsx_syncRequestHeaderInfo>
</soapenv:Header>
<soapenv:Body>
<ims:announceBulkDataExchangeRequest>
<ims:transactionId>123456</ims:transactionId>
<ims:bulkBlockManifest>
<ims:bulkBlockManifestId>123456</ims:bulkBlockManifestId>
<ims:expiryDate>2020-10-01T12:00:00</ims:expiryDate>
<ims:bulkBlockDataFile>
<ims:url>http://<your_test_file_server>:8081/<file_path>¬                               /SampleBulkRequest_PersonCourseMemberTerm.xml</ims:url>
<ims:checkSum>b3ecf4f05935c687932ce1d8c1af7335</ims:checkSum>
<ims:totalSize>29063</ims:totalSize>
<ims:savePoint>2020-10-01T12:00:00</ims:savePoint>
<ims:serviceSet>
<ims:serviceRecord>
<ims:serviceName>CourseManagementService</ims:serviceName>
<ims:interfaceName>CourseSectionManager</ims:interfaceName>
<ims:operationSet>
<ims:operationName>replaceCourseSection</ims:operationName>
</ims:operationSet>
</ims:serviceRecord>
</ims:serviceSet>
</ims:bulkBlockDataFile>
</ims:bulkBlockManifest>
</ims:announceBulkDataExchangeRequest>
</soapenv:Body>
</soapenv:Envelope>

Conjunto de dados 2: BulkDataRequest

Os elementos ims:imsx_messageIdentifier, ims:transactionId e ims:bulkBlockManifestId devem ter o mesmo valor (neste exemplo, o valor é 123456). Os elementos ims:expiryDate e ims:savePoint também devem ter o mesmo valor (no exemplo acima, o valor 2020-10-01T12:00:00 é usado).

O objeto ims:bulkBlockDataFile representa um arquivo em lote a ser operado. O elemento ims:url é a URL para o local do arquivo de feed de teste no servidor de arquivos. O elemento ims:totalSize é o tamanho total, em bytes, do arquivo de feed de teste (use 'ls -l' no Linux ou dir no Windows). O elemento ims:checkSum é o hash md5 do arquivo de teste (use md5sum no Linux ou obtenha um programa comparável ou Cygwin no Windows).

O objeto ims:serviceRecord representa como o arquivo de feed será processado; mais de um ims:serviceRecord pode existir em um elemento ims:bulkBlockDataFile. O elemento ims:serviceName representa o serviço web LIS cujas operações serão chamadas para processar o arquivo de feed fornecido. O elemento ims:interfaceName é a interface no código Sistema de informações do aluno (SIA) do LIS que será usada como o índice de métodos disponíveis para chamar. O objeto ims:operationSet contém a lista de métodos (relacionados como um elemento ims:operationName) que devem ser chamados para processar o arquivo de feed.

A solicitação é executada selecionando o botão "reproduzir" verde no canto superior esquerdo do quadro para a solicitação.

A resposta à solicitação acima é:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<ims:imsx_syncResponseHeaderInfo xmlns:ims="http://www.imsglobal.org/services/li.../imsbdems_v1p0">
<ims:imsx_version>V1.0</ims:imsx_version>
<ims:imsx_messageIdentifier>4ebf713ae3664f84ab67d961c3f55060</ims:imsx_messageIdentifier>
<ims:imsx_statusInfo>
<ims:imsx_codeMajor>success</ims:imsx_codeMajor>
<ims:imsx_severity>status</ims:imsx_severity>
<ims:imsx_messageRefIdentifier>123456</ims:imsx_messageRefIdentifier>
<ims:imsx_description>Use the reference code 9d4a22b81d4a45d683c2c13e0a0e7a1c to track these records in the logs.</ims:imsx_description>
<ims:imsx_codeMinor>
<ims:imsx_codeMinorField>
<ims:imsx_codeMinorFieldName>TargetEndSystem</ims:imsx_codeMinorFieldName>
<ims:imsx_codeMinorFieldValue>fullsuccess</ims:imsx_codeMinorFieldValue>
</ims:imsx_codeMinorField>
</ims:imsx_codeMinor>
</ims:imsx_statusInfo>
</ims:imsx_syncResponseHeaderInfo>
</soapenv:Header>
<soapenv:Body>
<ims:announceBulkDataExchangeResponse xmlns:ims="http://www.imsglobal.org/services/li.../imsbdems_v1p0"/>
</soapenv:Body>
</soapenv:Envelope>

O teste manual da integração antes da conexão com o SIA permite que você confirme a operação correta da configuração do Learn. O teste com uso da UI permite um teste rápido dos dados e do comportamento das configurações. O teste com uso do conjunto de ferramentas SoapUI permite não somente testar dados e comportamentos, mas também as configurações de conectividade e autorização, na forma como seriam transferidas do SIA. Isso permite uma separação das tarefas para estabelecer e fazer uma triagem da integração LIS.

O conjunto de dados de amostra (bbdn-lis_samples) usado neste tópico pode ser clonado ou baixado como um arquivo .zip do repositório Blackboard GitHub.

Baixe o SimpleHttpServer