How to "do" operations

If you have an active Translator ARA or KP, you're already doing operations. Congratulations! To start out, we just want to formally describe/document what's already happening. If you're interested in the new things that operations will allow us to do, all are welcome to attend the weekly meetings of the operations-and-workflow working group (OWWG).

The operations formalization defines what will be done or has been done with TRAPI messages. Operations are defined largely by what they are allowed to do to a TRAPI message, and what conditions must be met when they're done. Most Translator components are doing an operation that we call "lookup". It is defined as the operation that allows:

• adding knowledge graph elements
• adding results

and provides some guarantees about the output:

• Each result must include bindings for every query graph element.

Contrast this with operations that only add results ("bind") or modify the query graph ("restate") or anything else.

Right now, you don't need to worry about any of the fancy new operations, you just need to:

1. advertise which operations your Translator component can perform
2. parse the new workflow instructions in TRAPI requests

Advertising operations

In your OpenAPI schema, you already have information in the x-trapi extension. We need an additional field operations whose value is a list of operation identifiers. For most Translator components, it will look just like this:

info:
  x-trapi:
    version: 1.1.0
    operations:
    - lookup
    ...

Parsing instructions

TRAPI 1.2.x will include a new workflow field in each request:

{
    "message": ...,
    "workflow": [
        {"id": "lookup"}
    ]
}

It is the Translator component's responsibility to parse this workflow instruction and behave accordingly. If you're implementing lookup and the request looks like the above, you're good to go. If the requested workflow includes operations that are not included in your x-trapi advertisement, the client has made an improper request. Return an HTTP status code 400 with a helpful message.

More complicated situations

A couple situations may arise that will require more careful handling.

1. Your Translator component implements operations in addition to lookup. If appropriate operation definitions already exist, please advertise each of them and apply them upon request. Otherwise create an issue or pull request on the operations-and-workflow repository
2. You receive a workflow instruction with more than one element. If your component is not able to execute each instruction/operation, return an HTTP error 400 and do not attempt to process the query.