Skip to content

Resource Types

The SEAL Operator API allows clients to manipulate resources located on the server by calling the endpoints. These endpoints are mostly designed in CRUD (Create,Read,Update,Delete) style, so it is important to know the different types of available resources which and their relations.

Repositories

Repositories are not a resource by itself but the administration unit for documents and collections. All documents and collections are stored in a repository that acts as a data source and/or sink. The structure of a repository may be flat or tree-like. For the structuring, collections are used, (slightly similar to folders in a file system) but are kept more flexible in order to integrate DMS, ECMS, PLM and other systems. Repositories contain documents and/or collections. Collections contain documents and/or other collections. Each document and each collection has a unique identifier on server side.

Documents

Documents are the most important resource. For SEAL Operator, a document is a binary file with a set of accompanying metadata. The metadata in SEAL Operator is schema-free. Any metadata may be used as long as they can be represented as a single JSON object. Additionally to the metadata, a document contains some pre-defined properties, refer to the OpenAPI specification, RepoEntry schema.

Example - document for creation

{
  "name": "My special document",
  "type": "document",
  "metadata": {
    "arbitrary_key": "arbitrary value",
    "an_object": {
      "structure": "me"
    }
  }
}

After creating a new document, the server returns the document data including the generated properties like the document ID or the document href URL in links.self.href. Both can be used to access the document later on.

Example - create document response

{
  "uuid": "735c55d2-007f-442d-857c-df2f14805061",
  "name": "My special document",
  "type": "document",
  "metadata": {
    "arbitrary_key": "arbitrary value",
    "an_object": {
      "structure": "me"
    }
  },
  "links": {
    "self": {
      "href": "/v1/services/operator-fileupload/repo/c21dc371-b3bf-4727-baf6-8b1028b1434c"
    }
  }
}

Collections

Collections have the same general structure as documents and the same REST endpoints are used to manipulate them. The main difference is the type, which is collection instead of document.

Example - collection for creation

{
  "name": "directory 42",
  "type": "collection",
  "metadata": {
    "some_key": "some value",
    "an_object": {
      "just": "to show"
    }
  }
}

Like documents, a collection get a unique ID and an href URL property when being created by the server.

Lists

Documents and collections can be organized in lists. Lists are flat, ordered structures containing list items. Each list item can refer to a document or a collection via its href URL. Both the list itself and each item may contain metadata in addition to the metadata of the referenced document. List and list item metadata are schema-free JSON objects, as well. An index is assigned to the List items when being created. The index may change when changing the order of the items in the list. List are used to organize documents according to the user's needs (for example, when converting or printing documents in the correct order). Also, two lists are part of each task, representing the input and output data of the task.

Example - list for creation

{
  "name": "my list",
  "metadata": {
    "list": "metadata"
  },
  "embedded": {
    "listItems": [
      {
        "href": "/v1/services/operator-fileupload/repo/c21dc371-b3bf-4727-baf6-8b1028b1434c",
        "metadata": {
          "additional": "document metadata"
        }
      }
    ]
  }
}

When creating a list, the name property is the only mandatory property, all others are optional. After creating a list, the server returns the list data including the generated properties like the list ID and the (empty) list of items.

Tasks

Tasks describe data on which actions are executed, for example, conversion or printing. Tasks always exist in the context of the service that provides them, for example, PLOSSYS 4, PLOSSYS 5 or DPF.

Each task contains one input and one output list. Each list has its own additional metadata. The input list refers to the documents and collections to be processed. The combination of the task and the input list metadata controls the behavior of the task. The metadata used to control the task execution (for example, the Printer property for printing) depends on the service. Each service supports up to four task actions: start, abort, pause and resume. The start action is mandatory.

After the task has finished, the output list contains the generated metadata and refers to the result documents if available. Each service specifies the specific metadata of the output list.

Example - task for creation

{
  "name": "my task",
  "metadata": {
    "task": "metadata"
  },
  "lists": {
    "input": {
      "metadata": {
        "list": "metadata"
      },
      "embedded": {
        "listItems": [
          {
            "href": "/v1/services/operator-fileupload/repo/2fc14490-18cc-4271-a9a5-e78a313ca021",
            "metadata": {
              "additional": "document metadata"
            }
          },
          {
            "href": "/v1/services/operator-fileupload/repo/bdd0c0df-bb2a-4164-ab06-d07d10ae05bc",
            "metadata": {
              "more": "metadata"
            }
          }
        ]
      }
    }
  }
}

When creating a task, the name property is the only mandatory property, all others are optional. After creating a task, the server returns the task data including the generated properties including the task ID.

Panels

Panels are only used in the user interface of SEAL Operator for displaying other resources such as tasks, documents or collections. Panels are not needed unless user interaction is required.

According to the basic functions of services, two types of panels are available in SEAL Operator:

  • Repository panels are used to show the repository contents and their structure. Multiple panels can be opened for each repository, similar to what is possible in a file system explorer.
  • Task panels are used to show, configure and start tasks. Each task panel has one task. A task may belong to no or one panel.

Example - repository panel for creation

{
  "serviceId" : "operator-fileupload",
  "name" : "My special Documents",
  "type" : "scratch"
}

The serviceId property specifies the name of the repository service. The value of the type property is predefined by the repository service. The name property is displayed as panel name in the user interface. If no name has been specified, a unique ID will be created by the server.

Example - task panel for creation

{
    "serviceId" : "operator-p5",
    "name" : "PLOSSYS 5",
    "type" : "print",
    "taskId" : "e0321524-b312-4eb4-ba93-8e84be2a3047"
}

Via the taskId property, the task panel is connected to task which has to be created before. The serviceId property specifies the name of the repository service. The value of the type property is predefined by the task service. The name property is displayed as panel name in the user interface. If no name has been specified, a unique ID will be created by the server.

After creating a panel, the server returns the panel data including the generated properties including the panel ID.

Next Step

Continue with: Use Cases

Back to top