CTT

    Serviços de Integração (EAI) - Repositório Documental de Aplicações

API de Gestão Documental

A API de Gestão Documental (CMISGatewayRS) é uma API REST desenvolvida com recurso a produtos de integração seguros e robustos que asseguram uma comunicação transparente entre ambientes produtivos com sistemas e tecnologias heterogênias.

Através da presente API é possível invocar o CMIS e assim realizar as seguintes operações de gestão documental sobre o FileNet:

  • Criar documentos no repositório;
  • Remover documentos no repositório;
  • Obter documentos no repositório;
  • Atualizar documentos no repositório;
  • Obter conteúdo de documentos no repositório;
  • Obter link para conteúdo de documentos no repositório;
  • Obter propriedades de documentos no repositório;
  • Atualizar propriedades de documentos no repositório;
  • Procurar documentos no repositório;
  • Procurar classes no repositório;
  • Procurar propriedades de uma classe no repositório;

A definição destas operações expostas nos interfaces seguem a norma RESTful e um modelo de comunicação síncrono, o que exige a necessidade de manter a comunicação entre a realização dos pedidos e obtenção das respostas.


Especificação de modelos

A definição das entidades e modelos definidos está disponível em Swagger de acordo com a especificação OpenAPI versão 2.0.

Payload de input - Criação de documento

Modelo que representa o payload de input para a criação de documentos no FileNet.


Modelo Tipo de Dados Opcional Descrição
CreateDocumentRequest JSON.Object Payload de input com documento a criar.
properties JSON.Object Sim Propriedades do documento.
folderId String Sim ID da pasta onde vai ser criado o documento.
content JSON.Object Sim Conteúdo do documento.

Exemplo:

{
    "content": {
        "filename": "124_Teste1.jpg",
        "stream": "dGVzdGU="
    }
}
CMISObject

Modelo canónico de um objeto/documento no FileNet. É o modelo devolvido nas interfaces que implementam o GET e pesquisa (POST) de informação de documento(s).


Modelo Tipo de Dados Opcional Descrição
CMISObject JSON.Array CMIS Object.
properties JSON.Object Sim Propriedades do documento.
allowableActions JSON.Object Sim
 Ações permitidas ao objeto.
relationship JSON.Array Sim Objeto dependente.
changeEventInfo JSON.Object Sim Track de update do objeto.
acl JSON.Object Sim Lista de controlo de acesso.
exactACL Boolean Sim Indicador se ACL retornado descreve na íntegra a permissão do objeto. Default: False.
policyIds JSON.Object Sim Ids das políticas aplicadas ao objeto.
rendition JSON.Array Sim Representações alternativas do documento.
extension JSON.Array Sim Objecto para extender o schema.

Exemplo:

{
   "properties":    {
      "propertyDateTime":       [
                  {
            "propertyDefinitionId": "cmis:creationDate",
            "value": ["2020-05-14 11:26:42.466"],
            "localName": "DateCreated",
            "displayName": "Date Created",
            "queryName": "cmis:creationDate"
         },
                  {
            "propertyDefinitionId": "ContentRetentionDate",
            "localName": "ContentRetentionDate",
            "displayName": "Content Retention Date",
            "queryName": "ContentRetentionDate"
         },
                  {
            "propertyDefinitionId": "DateCheckedIn",
            "value": ["2020-05-14 11:26:42.467"],
            "localName": "DateCheckedIn",
            "displayName": "Date Checked In",
            "queryName": "DateCheckedIn"
         },
                  {
            "propertyDefinitionId": "cmis:lastModificationDate",
            "value": ["2020-05-14 11:26:42.466"],
            "localName": "DateLastModified",
            "displayName": "Date Last Modified",
            "queryName": "cmis:lastModificationDate"
         },
                  {
            "propertyDefinitionId": "DateContentLastAccessed",
            "localName": "DateContentLastAccessed",
            "displayName": "Date Content Last Accessed",
            "queryName": "DateContentLastAccessed"
         }
      ],
      "propertyInteger":       [
                  {
            "propertyDefinitionId": "VersionStatus",
            "value": [1],
            "localName": "VersionStatus",
            "displayName": "Version Status",
            "queryName": "VersionStatus"
         },
                  {
            "propertyDefinitionId": "MajorVersionNumber",
            "value": [1],
            "localName": "MajorVersionNumber",
            "displayName": "Major Version Number",
            "queryName": "MajorVersionNumber"
         },
                  {
            "propertyDefinitionId": "CmIndexingFailureCode",
            "localName": "CmIndexingFailureCode",
            "displayName": "Indexing Failure Code",
            "queryName": "CmIndexingFailureCode"
         },
                  {
            "propertyDefinitionId": "MinorVersionNumber",
            "value": [0],
            "localName": "MinorVersionNumber",
            "displayName": "Minor Version Number",
            "queryName": "MinorVersionNumber"
         },
                  {
            "propertyDefinitionId": "ClassificationStatus",
            "value": [0],
            "localName": "ClassificationStatus",
            "displayName": "Classification Status",
            "queryName": "ClassificationStatus"
         },
                  {
            "propertyDefinitionId": "ReservationType",
            "localName": "ReservationType",
            "displayName": "Reservation Type",
            "queryName": "ReservationType"
         },
                  {
            "propertyDefinitionId": "cmis:contentStreamLength",
            "value": [5],
            "localName": "ContentSize",
            "displayName": "Content Size",
            "queryName": "cmis:contentStreamLength"
         }
      ],
      "propertyId":       [
                  {
            "propertyDefinitionId": "cmis:objectId",
            "value": ["idd_D0B81272-0000-C11B-AFC9-76F7D1CE01F6"],
            "localName": "Id",
            "displayName": "ID",
            "queryName": "cmis:objectId"
         },
                  {
            "propertyDefinitionId": "IndexationId",
            "localName": "IndexationId",
            "displayName": "Indexation Id",
            "queryName": "IndexationId"
         },
                  {
            "propertyDefinitionId": "cmis:baseTypeId",
            "value": ["cmis:document"],
            "localName": "",
            "displayName": "cmis:baseTypeId",
            "queryName": "cmis:baseTypeId"
         },
                  {
            "propertyDefinitionId": "cmis:objectTypeId",
            "value": ["cmis:document"],
            "localName": "",
            "displayName": "cmis:objectTypeId",
            "queryName": "cmis:objectTypeId"
         },
                  {
            "propertyDefinitionId": "cmis:contentStreamId",
            "value": ["-1"],
            "localName": "",
            "displayName": "cmis:contentStreamId",
            "queryName": "cmis:contentStreamId"
         },
                  {
            "propertyDefinitionId": "cmis:versionSeriesId",
            "value": ["idv_D0B81272-0000-C41F-AE1C-75B999889BF0"],
            "localName": "VersionSeries",
            "displayName": "Version Series",
            "queryName": "cmis:versionSeriesId"
         },
                  {
            "propertyDefinitionId": "cmis:versionSeriesCheckedOutId",
            "localName": "",
            "displayName": "cmis:versionSeriesCheckedOutId",
            "queryName": "cmis:versionSeriesCheckedOutId"
         }
      ],
      "propertyBoolean":       [
                  {
            "propertyDefinitionId": "IsVersioningEnabled",
            "value": [true],
            "localName": "IsVersioningEnabled",
            "displayName": "Is Versioning Enabled",
            "queryName": "IsVersioningEnabled"
         },
                  {
            "propertyDefinitionId": "cmis:isLatestVersion",
            "value": [true],
            "localName": "IsCurrentVersion",
            "displayName": "Is Current Version",
            "queryName": "cmis:isLatestVersion"
         },
                  {
            "propertyDefinitionId": "IsReserved",
            "value": [false],
            "localName": "IsReserved",
            "displayName": "Is Reserved",
            "queryName": "IsReserved"
         },
                  {
            "propertyDefinitionId": "cmis:isImmutable",
            "value": [false],
            "localName": "IsFrozenVersion",
            "displayName": "Is Frozen Version",
            "queryName": "cmis:isImmutable"
         },
                  {
            "propertyDefinitionId": "CmIsMarkedForDeletion",
            "value": [false],
            "localName": "CmIsMarkedForDeletion",
            "displayName": "Is Marked For Deletion",
            "queryName": "CmIsMarkedForDeletion"
         },
                  {
            "propertyDefinitionId": "IsInExceptionState",
            "value": [false],
            "localName": "IsInExceptionState",
            "displayName": "Is In Exception State",
            "queryName": "IsInExceptionState"
         },
                  {
            "propertyDefinitionId": "cmis:isMajorVersion",
            "value": [true],
            "localName": "",
            "displayName": "cmis:isMajorVersion",
            "queryName": "cmis:isMajorVersion"
         },
                  {
            "propertyDefinitionId": "cmis:isLatestMajorVersion",
            "value": [true],
            "localName": "",
            "displayName": "cmis:isLatestMajorVersion",
            "queryName": "cmis:isLatestMajorVersion"
         },
                  {
            "propertyDefinitionId": "cmis:isVersionSeriesCheckedOut",
            "value": [false],
            "localName": "",
            "displayName": "cmis:isVersionSeriesCheckedOut",
            "queryName": "cmis:isVersionSeriesCheckedOut"
         }
      ],
      "propertyString":       [
                  {
            "propertyDefinitionId": "cmis:createdBy",
            "value": ["FILENETDSDCONTENTENG"],
            "localName": "Creator",
            "displayName": "Creator",
            "queryName": "cmis:createdBy"
         },
                  {
            "propertyDefinitionId": "cmis:name",
            "value": ["idd_D0B81272-0000-C11B-AFC9-76F7D1CE01F6"],
            "localName": "Name",
            "displayName": "Name",
            "queryName": "cmis:name"
         },
                  {
            "propertyDefinitionId": "cmis:lastModifiedBy",
            "value": ["FILENETDSDCONTENTENG"],
            "localName": "LastModifier",
            "displayName": "Last Modifier",
            "queryName": "cmis:lastModifiedBy"
         },
                  {
            "propertyDefinitionId": "DocumentTitle",
            "localName": "DocumentTitle",
            "displayName": "Document Title",
            "queryName": "DocumentTitle"
         },
                  {
            "propertyDefinitionId": "CurrentState",
            "localName": "CurrentState",
            "displayName": "Current State",
            "queryName": "CurrentState"
         },
                  {
            "propertyDefinitionId": "cmis:changeToken",
            "value": ["0"],
            "localName": "",
            "displayName": "cmis:changeToken",
            "queryName": "cmis:changeToken"
         },
                  {
            "propertyDefinitionId": "cmis:checkinComment",
            "localName": "",
            "displayName": "cmis:checkinComment",
            "queryName": "cmis:checkinComment"
         },
                  {
            "propertyDefinitionId": "cmis:contentStreamMimeType",
            "value": ["image/jpeg"],
            "localName": "MimeType",
            "displayName": "Mime Type",
            "queryName": "cmis:contentStreamMimeType"
         },
                  {
            "propertyDefinitionId": "cmis:contentStreamFileName",
            "value": ["124_Teste1.jpg"],
            "localName": "",
            "displayName": "cmis:contentStreamFileName",
            "queryName": "cmis:contentStreamFileName"
         },
                  {
            "propertyDefinitionId": "cmis:versionLabel",
            "value": ["1.0"],
            "localName": "",
            "displayName": "cmis:versionLabel",
            "queryName": "cmis:versionLabel"
         },
                  {
            "propertyDefinitionId": "cmis:versionSeriesCheckedOutBy",
            "localName": "",
            "displayName": "cmis:versionSeriesCheckedOutBy",
            "queryName": "cmis:versionSeriesCheckedOutBy"
         }
      ],
      "extension": [      {
         "key": "GUID",
         "value": "{D0B81272-0000-C11B-AFC9-76F7D1CE01F6}",
         "namespace": "http://www.ibm.com/xmlns/prod/ecm/cmis/p8extensions"
      }]
   },
   "changeEventInfo":    {
      "changeType": "updated",
      "changeTime": "2020-05-14 11:26:42.466"
   }
}
CMISContentStreamLink

O modelo CMISContentStreamLink representa a estrutura que engloba o link para o conteúdo do documento.


Modelo Tipo de Dados Opcional Descrição
CMISContentStreamLink JSON.Object Informação do link para o conteúdo do documento.
length Integer Sim Tamanho da stream de conteúdo em bytes.
mimeType String Sim MIME Media Type da stream de conteúdo.
filename String Não Nome do ficheiro (objectID_filename para garantir unicidade).
directory String Não Diretoria do ficheiro no IBM Sterling para o utilizador em específico.
extension JSON.Array Sim Objecto para extender o schema.

Exemplo:

{
	"length": "142733",
	"mimeType": "image/jpeg",
	"filename": "idd_308EC071-0000-C21F-82ED-34218CC9E187_124_Teste.jpg",
	"directory": "/Inbox/cttiib"
}
CMISContentStream

O modelo CMISContentStream representa a estrutura que engloba o conteúdo do documento.


Modelo Tipo de Dados Opcional Descrição
CMISContentStream JSON.Object Informação do conteúdo do documento.
length Integer Sim Tamanho da stream de conteúdo em bytes.
mimeType String Sim MIME Media Type da stream de conteúdo.
filename String Sim Nome do ficheiro.
stream String Não Stream de conteúdo em Base64.
extension JSON.Array Sim Objecto para extender o schema.

Exemplo:

{
	"length": "5",
	"mimeType": "image/jpeg",
	"filename": "124_Teste1.jpg",
	"stream": "dGVzdGU="
}
SearchDocumentsFilter

O modelo SearchDocumentsFilter representa a estrutura que define uma pesquisa de documentos no FileNet.


Modelo Tipo de Dados Opcional Descrição
SearchDocumentsFilter JSON.Object Payload de pesquisa de documentos.
statement String Não Statement SQL para procura de documentos.
maxItems String Sim Número máximo de itens a serem retornados.

Exemplo:

{
    "statement": "SELECT * FROM cmis:document",
    "maxItems": 2
}
SearchClassesFilter

O modelo SearchClassesFilter representa a estrutura que define uma pesquisa de classes no FileNet.


Modelo Tipo de Dados Opcional Descrição
SearchClassesFilter JSON.Object Payload de pesquisa de classes.
appId String Não Id da aplicação.

Exemplo:

{
    "appId":"CTT"
}
SearchClassPropertiesFilter

O modelo SearchClassPropertiesFilter representa a estrutura que define uma pesquisa de propriedades de uma classe no FileNet.


Modelo Tipo de Dados Opcional Descrição
SearchClassPropertiesFilter JSON.Object Payload de pesquisa de propriedades de uma classe.
appId String Não Id da aplicação.
classId String Não Id da classe.

Exemplo:

{
    "appId":"CTT",
    "classId":"{00C77658-0000-C211-9AD1-80FCA3D53C4A}"
}
SearchClassesResponseList

O modelo SearchClassesResponseList representa a estrutura de output de uma pesquisa de classes no FileNet.


Modelo Tipo de Dados Opcional Descrição
SearchClassesResponseList JSON.Object Payload de output de uma pesquisa de classes.

Exemplo

SearchClassPropertiesResponseList

O modelo SearchClassPropertiesResponseList representa a estrutura de output de uma pesquisa de propriedades de uma classe no FileNet.


Modelo Tipo de Dados Opcional Descrição
SearchClassPropertiesResponseList JSON.Object Payload de output de uma pesquisa de propriedades de uma classe.

Exemplo:

{
	"list": [
		{
			"symbolicName": "DocumentTitle",
			"displayName": "Document Title",
			"id": "{A47A2B50-010F-4AB3-85D4-DC9FC39CA5E9}",
			"dataType": "STRING"
		},
		{
			"symbolicName": "ComponentBindingLabel",
			"displayName": "Component Binding Label",
			"id": "{80679693-A583-413E-AE22-7C71B2E88F74}",
			"dataType": "STRING"
		},
		{
			"symbolicName": "IgnoreRedirect",
			"displayName": "Ignore Redirect",
			"id": "{DBF31A66-DF56-4711-9778-D9379F2F8331}",
			"dataType": "BOOLEAN"
		},
		{
			"symbolicName": "EntryTemplateObjectStoreName",
			"displayName": "Entry Template Object Store Name",
			"id": "{B363DDCC-B33E-435E-859C-7A24F6E91BEC}",
			"dataType": "STRING"
		},
		{
			"symbolicName": "EntryTemplateLaunchedWorkflowNumber",
			"displayName": "Entry Template Launched Workflow Number",
			"id": "{9F436F96-7F3D-4D03-A364-393B67557352}",
			"dataType": "STRING"
		},
		{
			"symbolicName": "EntryTemplateId",
			"displayName": "Entry Template Id",
			"id": "{30F1D5E5-7CF0-4725-B7E8-139C4F997CB8}",
			"dataType": "GUID"
		},
		{
			"symbolicName": "spSecurityParentBPO",
			"displayName": "Security Parent BPO",
			"id": "{ECD309DF-40E1-410D-ABC6-6CDDEEB6B12C}",
			"dataType": "OBJECT"
		},
		{
			"symbolicName": "ptGUID",
			"displayName": "GUID",
			"id": "{6A89AA99-78B0-4F42-A207-216B5A25E0E3}",
			"dataType": "STRING"
		}
	]
}

Interfaces Disponíveis

A tabela abaixo descreve os interfaces disponibilizados pela API para as operações referidas anteriomente na secção introdutória:


# Operação Resource
1 Criar documentos no repositório. POST /document
2 Remover documentos no repositório. DELETE /document
3 Obter documentos no repositório. GET /document
4 Atualizar documentos no repositório. PATCH /document
5 Obter conteúdo de documentos no repositório. GET /document/content
6 Obter link do conteúdo de documentos no repositório. GET /document/link
7 Obter propriedades de documentos no repositório. GET /document/properties
8 Atualizar propriedades de documentos no repositório. PATCH /document/properties
9 Procurar documentos no repositório. POST /documents/search
10 Procurar classes no repositório. POST /classes/search
11 Procurar propriedades de uma classe no repositório. POST /class/properties/search

Os interfaces são disponibilizados em servidor Apache Tomcat e seguem o protocolo HTTP/1.1. Nas invocações realizadas aos interfaces de pesquisa (expostas em interfaces POST), os payloads de input deverão ser codificados em UTF-8. O media type a utilizar nas mensagens com payload de input deverá ser application/json.


Construção de endpoints

Os interfaces disponibilizados pela API são geralmente compostos por sete partes distintas como ilustrado na tabela abaixo. A título de exemplo, será utilizado o interface de pesquisa de documentos:


https://api.qa.ctt.pt/qualidade-01/internal/cmisgatewayrs/v1/documents/search


Protocolo https
Hostname/servidor CTT api.qa.ctt.pt
Ambiente Qualidade
Catálogo internal
Identificação da API cmisgatewayrs
Versão v1
Resource do serviço documents/search

Projetos de Teste

A configuração do ambiente para a realização de pedidos aos diferentes serviços disponibilizados pela API requer a utilização de software para testes automáticos (automated testing) como SoapUI ou Postman. Em alternativa, poderão também ser utilizadas ferramentas de linha de comandos como o cURL ou qualquer outra ferramenta de transferência de dados compatível com o protocolo HTTP.

Para efeitos de teste, disponibiliza-se o seguinte projeto de SoapUI:


Execução dos testes

O primeiro passo será realizar a importação do projeto de testes através do menu File:

File → Import Project



De seguida surgirá uma janela para carregar o projeto de testes disponibilizado para download no topo desta secção. Em alternativa, também é possível realizar a importação do projeto através da combinação Ctrl+I.

A expansão dos diferentes resources após a importação do projeto, permitirá visualizar a listagem dos diferentes casos de teste para cada interface. Cada interface poderá ter disponível um ou mais casos de teste distintos.

Para executar um teste a um determinado interface basta escolher o caso de teste pretendido:



A execução do teste é realizado através do apontador verde assinalado na figura seguinte:



Sendo que o interface de teste na imagem de exemplo é um POST, a informação recebida no pedido é obtida no painel "JSON" do lado direito da figura.

O resultado global de sucesso da transação pode ser aferido pelo conteúdo dos seguintes headers devolvidos na resposta:

  1. X-Original-HTTP-Status-Code (200)
  2. x-iib-StatusCode (X0)
  3. x-iib-StatusMessage (Success)
  4. #status# (HTTP/1.0 200 OK)

Entre os restantes headers devolvidos na resposta, destaca-se também o header x-iib-TransactionID. O valor deste header representa um identificador único e universal. Por essa razão identifica de forma unívoca a transação realizada, e pode ser utilizado para efeitos de auditoria ou deteção de anomalias.