1. Who is this document for?

This document is aimed at developers building connections to LocHub via the TAPICC API, and other parties interested in the LocHub implementation of the TAPICC specification.

The present document aims to provide developers with some context and advice on implementing the workflows supported by TAPICC when building an integration with the LocHub TAPICC API.

This guide does not provide reference documentation about the API, which can be found at /#/help of any LocHub instance.

2. What is TAPICC?

The Translation API Cases and Classes (TAPICC) initiative is a collaborative, community-driven, open-source project to advance API standards for multilingual content delivery. The overall purpose of this initiative is to provide a metadata and API framework on which users can base their integration, automation, and interoperability efforts.
The current published standard for the TAPICC API is version 0.0.7.

TAPICC is a new standard elaborated by several working groups to analyze and standardize the "content transformation" business. Focusing primarily on translations.

The standard follows a set of guiding principles:

  • TAPICC is about the exchange of information between system processes in the content industry.

  • TAPICC does not replace CMSs or TMSs.

  • Document, User, Role, and Workflow management are out of scope of the standard.

    • the TAPICC model works with immutable snapshots of documents.

    • TAPICC does not specify any User or Role model, nor any Authorization policy.

    • TAPICC does not dictate what the next step after a task has been completed is. This is left to the collaborating parties.

    • TAPICC does not replace or overlap with other initiatives in the field of content exchange formats, nor uniform Content APIs such as CMIS.

    • TAPICC promotes and supports but does not impose standardization of the translatable payload.

    • TAPICC does not interpret payloads, i.e. does not provide word counts, does not transform content.

2.1. Support for Industry Standards

The XML Localization Interchange File Format (XLIFF) standard is a common format used to standardize the way localizable data is passed between tools. XLIFF files are supported by the LocHub TAPICC API implementation in so far as they can be uploaded and downloaded, just like any other file format, such as a source or bitext.

3. Workflow for a Translation

3.1. Roles

There are two main actors in the various use cases for the LocHub TAPICC API implementation:

Content Owner
The Content Owner owns the content to be processed. They manage and configure the translation Job, its Tasks, and related Inputs. A Content Owner, for example, could be a marketing consultant who needs some promotional documents translated or a website content editor who needs web pages translated for international customers.

Service Provider
The Service Provider supplies content processing services. They access the source and supporting documents and perform translation operations. A Service Provider in this context can be, for example, a Language Service Provider (LSP).

Service Providers own the Deliverables associated with a Task. These are the results of a translation action.

3.2. LocHub TAPICC Implementation

LocHub aims to enable large-scale enterprise translation projects to be fully automated and independent of tooling. The project goals are to reduce workload through automation, thus increasing the throughput of translation tasks while maintaining transparent and manageable oversight and control.

LocHub offers to 3rd parties (customers, partners, etc.) an API to integrate with. LocHub embraces the TAPICC initiative and seeks to contribute to the standard.

Currently, LocHub implements a fraction of the TAPICC v0.0.7 specification:

  • Only the translation workflow is implemented.

  • Some webhooks are implemented, only events taskCreated, taskUpdated and taskDeleted are supported.

  • The TIPP endpoint is not supported since the REST endpoint can provide better information.

The TAPICC standard defines a list of file types to describe input files and deliverables files. It is the Content Owner’s responsibility to ensure the file type specified corresponds to the actual file uploaded. LocHub does not validate it is correct or meaningful.

LocHub also adds two extensions to TAPICC: Projects and Assets in the 1.0.0-BETA version.

3.2.1. Simple LocHub TAPICC Entity Relationship Diagram

diag 6b63638d446d1df68e2126d8d54d549b
Figure 1. Simple TAPICC ERD

3.2.2. Authentication and Authorization

All LocHub TAPICC endpoints require an OAuth2 bearer token. To get an access token use the LocHub’s OAuth endpoint.

Endpoint
    POST https://tenant.lochub.com/oauth/token
Headers
    Content-Type: multipart/form-data
Body
    grant_type: password
    client_id: app
    username: <<your username>>
    password: <<your password>>

3.3. Successful Translation Flow

diag af44a88d0093a5f86430c3a0714531f3
Figure 2. Successful Translation Sequence Diagram

3.3.1. Create Job

Content Owner performs this action

A Job is the owner of resources such as translation source documents and reference documents (Inputs), translated documents (Deliverables), and their associated Tasks.

  • A successful response returns the details of the newly created Job, including the JobId identifier.

  • A Job may have one or more Tasks, Inputs, and or Deliverables, related to it. Refer to the LocHub TAPICC ERD.

Endpoint and Expected Response Code
    POST https://tenant.lochub.com/api/tapicc/1.0.0-beta/jobs
    -------------------
    HTTP/1.1 201 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Body
    {
        "submitter": "mycompany.com/123456", (1)
        "name": "the name of the Job",
        "description": "detailed description of the Job",
        "metadata": { (2)
            "ourId": "uuid"
        },
        "dueDate": "2019-08-27T12:07:48.575Z" (3)
    }
1 The submitter field is a free form reference to a user on the originating system, not the user logged in the TAPICC API.
2 The metadata field is a free form map of key-value pairs to store any additional data related to the entity.
3 All dates must be ISO 8601 compliant, and must contain time specification up to minutes.

3.3.2. Create Task

Content Owner performs this action

It is recommended to create a Task for each source document that is to be translated. As a Task defines the discrete properties and state of the activity to be performed on an Input, this strategy allows finer granular control. It is possible to assign multiple Inputs to a Task, and this may be required to provide supporting documents, but multiple source documents are discouraged since they would be treated as a unit, making the API less versatile.
Tasks also maintain a status flag of which there are a finite set of allowed values. Refer to the state transition diagram: Task States.

LocHub at the moment supports only the translation Task type.
Endpoint and Expected Response Code
    POST https://tenant.lochub.com/api/tapicc/1.0.0-beta/tasks
    -------------------
    HTTP/1.1 201 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Body
{
    "jobId": "abaa9c70-0382-456e-9dc8-ad6fa83e7888",
    "name" : "Translate report to Czech",
    "type": "translation",
    "sourceLanguage": "en",  (1)
    "targetLanguage": "cz",  (2)
}
1 Language codes must comply with IETF BCP47 standard tags.
2 Both sourceLanguage and targetLanguage values must be provided for a Task.
Content Owner performs this action

To upload a piece of content, an Asset needs to be created in a Project. This Asset can then be linked to a Task as an Input. There are also a number of optional and mandatory properties such as the original file name, the MIME type, and creation date.

Inputs represent the relationship of files, provided by the Content Owner, that feed into a translation pipeline, and the workload units - Tasks. An Input is not always the source of the translation material, there are multiple Input types. Depending on the case, it could be some related content such as (but not limited to):

  • Supporting document with instructions for the translator.

  • Rendered document as a reference to a source XML

  • A translation memory to be used.

  • A glossary.

An Input also maintains a number of other relationships such as the related Job, and Deliverables.

LocHub TAPICC implementation offers two options. Either creating Asset and Input separately with two API requests or creating them with one combined API request. This guide provides an example of the combined method.

Endpoint and Expected Response Code
    POST https://tenant.lochub.com/api/tapicc/1.0.0-beta/inputs/-combined
    -------------------
    HTTP/1.1 201 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: multipart/form-data
    Accept: application/json
Table 1. Body Parts for multipart/form-data
Body part Description

input

Metadata of the Input and Asset, JSON format

content

Stream with the actual binary content of the Asset

Input example
{
    "taskId": "ab719c60-0392-456e-9118-ad6fa83e7173",
    "name": "My Report",
    "description": "First draft of the report",
    "fileOriginalName": "report.docx",
    "inputAs": "source",
    "language": "en-US",
    "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "projectId": "46893d5f-e21f-4c92-93d2-9c10deafca49",
    "metadata": {
        "key1": "value"
    }
}

3.3.4. Confirm Task is Ready

Content Owner performs this action

To make a Task ready for processing by a Service Provider, it must have its status set to confirmed by the Content Owner. Before this happens the Service Provider should not operate on the Task or its Inputs.

At least one source Input must be associated with a Task before its status can be set to confirmed.
Endpoint and Expected Response Code
    PATCH https://tenant.lochub.com/api/tapicc/1.0.0-beta/tasks/{id}
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Body
{
    "status" : "confirmed"
}

3.3.5. Start Tasks

Service Provider performs this action

When the Service Provider wants to start working on the Task they update its status to in_progress, optionally setting the assignedTo field with a free form reference to their internal user.

If the Task is ill-defined, for example because it is missing a necessary reference Input, the Service Provider would set the Task status to rejected and write the reason for rejection in the field note.

Endpoint and Expected Response Code
    PATCH https://tenant.lochub.com/api/tapicc/1.0.0-beta/tasks/{id}
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Body
{
    "status" : "in-progress"
}

3.3.6. Upload Deliverables

Service Provider performs this action

Once a Service Provider has completed the content transformation of a Task Input, a Deliverable should be created and its content uploaded.

Like Input, also Deliverable is linked to Asset which holds the actual binary content of the Deliverable. And like Input, also Deliverable can be created by couple of API requests (to create an Asset and to create a Deliverable) or with one combined API request.

Endpoint and Expected Response Code
    POST https://tenant.lochub.com/api/tapicc/1.0.0-beta/deliverables/-combined
    -------------------
    HTTP/1.1 201 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: multipart/form-data
    Accept: application/json
Table 2. Body Parts for multipart/form-data
Body part Description

deliverable

The new Deliverable and Asset values, JSON format

content

Actual binary content of the Asset

Deliverable example
{
    "deliverableAs": "source",
    "name": "Report in Czech",
    "fileOriginalName": "report-cs.docx",
    "language": "cs-CZ",
    "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "projectId": "46893d5f-e21f-4c92-93d2-9c10deafca49",
    "jobId": "e0e41177-0301-4454-a9db-7118baaaaf5d",
    "taskId": "7c8121f8-4431-4e9d-8164-40afa205e9e9",
    "inputId": "c4ab9f5a-4dfc-4aea-807e-9b6e116c1acd",
    "metadata": {
        "key": "value"
    }
}
Currently, LocHub allows creating only Deliverables of type source.

3.3.7. Complete Task

Service Provider performs this action

When the Service Provider has finished uploading the Deliverables of a Task, they set the status of the Task to completed. This communicates to the Content Owner that the Task is not going to change and that the results are attached to it as Deliverables.

Endpoint and Expected Response Code
    PATCH https://tenant.lochub.com/api/tapicc/1.0.0-beta/tasks/{id}
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Body
    {
        "status" : "completed"
    }

3.3.8. Get Deliverables

Content Owner performs this action

Once the Service Provider has uploaded their completed translations, and set the Task status to completed, the Content Owner is able to download the Deliverables.

Get Deliverable Ids

To access Deliverables for a Task, the Content Owner must first get the metadata about the Task which includes a list of Deliverable identifiers. Using these ids, they can then request the metadata and content of a Deliverable (i.e. the translated document).

Endpoint and Expected Response Code
    GET https://tenant.lochub.com/api/tapicc/1.0.0-beta/tasks/{id}
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Example response
    {
      "id": "ef2dd5c7-2c70-4701-9685-b63b76633cfb",
      "createdAt": "2021-10-15T06:35:11.51947Z",
      "updatedAt": "2021-10-15T07:21:37.714018Z",
      "name": "What is TAPICC",
      "status": "completed",
      "type": "translation",
      "submittedAt": "2021-10-15T06:35:11.633509Z",
      "deliveredAt": "2021-10-15T07:20:52.924471Z",
      "sourceLanguage": "en",
      "targetLanguage": "fr",
      "jobId": "667d5e84-9104-46b9-9473-2a7c64007d4c",
      "inputs": {
        "f7394e1b-2a64-4626-81a3-09fe74d910bb": "source"
      },
      "deliverables": {
        "bb0f224b-3482-4e4c-9bf0-cb89b9b834a6": "source"
      }
    }
Get Deliverable Metadata
Endpoint and Expected Response Code
    GET https://tenant.lochub.com/api/tapicc/1.0.0-beta/deliverables/{id}
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Example response
    {
      "id": "bb0f224b-3482-4e4c-9bf0-cb89b9b834a6",
      "projectId": "fa00614c-5eae-4601-a89f-09814e89e60f",
      "jobId": "667d5e84-9104-46b9-9473-2a7c64007d4c",
      "assetId": "62f6f7ed-0eb6-4145-a798-da038129e073",
      "taskId": "ef2dd5c7-2c70-4701-9685-b63b76633cfb",
      "inputId": "f7394e1b-2a64-4626-81a3-09fe74d910bb",
      "deliverableAs": "source",
      "name": "Quoi_est_TAPICC.xlf",
      "mimeType": "application/xml",
      "fileOriginalName": "Quoi_est_TAPICC.xlf",
      "size": 4802,
      "language": "fr",
      "state": "complete",
      "createdAt": "2021-10-15T07:20:50.273091Z",
      "updatedAt": "2021-10-15T07:20:50.273091Z"
    }

3.3.9. Download Deliverable Contents

Content Owner performs this action

Once the Content Owner has the Deliverable metadata, then they can request the associated content (stored as an Asset). Each request represents a request to download an individual file.

Endpoint and Expected Response Code
    GET https://tenant.lochub.com/api/tapicc/1.0.0-beta/assets/{id}/content
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Accept: application/octet-stream

3.3.10. Bulk Download Task Deliverables' Contents

Content Owner performs this action

Alternatively, all Deliverables related to a single Task can be downloaded in a .zip archive by a single request.

Endpoint and Expected Response Code
    GET https://tenant.lochub.com/api/tapicc/1.0.0-beta/tasks/{taskId}/downloaddeliverables

Parameters
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Accept: application/zip

3.3.11. Webhooks

Webhooks are a popular pattern to deliver notifications between applications and via HTTP endpoints. Applications that make notifications available, allow for other applications to register an HTTP endpoint to which notifications are delivered.

The main goal of webhooks in LocHub Orchestrate is to offer to 3rd parties that integrate with LocHub a mechanism to get notifications about events. Currently only 3 event types are supported - taskCreated, taskUpdated and taskDeleted. In future there may be added also event types jobCreated, jobUpdated, jobDeleted, inputCreated, inputUpdated, inputDeleted, deliverableCreated, deliverableUpdated and deliverableDeleted.

Webhook notification request

Notifications are delivered using an HTTP request. Usage of HTTP-over-TLS (HTTPS) for the connection is highly recommended. Currently only HTTP Basic authentication is supported. The HTTP method POST is used for all the delivery requests. The content type of the request’s payload is JSON.

Request example
{
  "id" : "8fadf454-b71b-4408-b20e-a61767b0c94f",
  "createdAt" : "2021-12-12T07:07:26.498489Z",
  "type" : "taskUpdated",
  "webhookId" : "abaa9c70-0382-456e-9dc8-ad6fa83e7888",
  "tryNumber" : 1,
  "task" : {
    "id" : "f1b39044-8fb2-4486-9561-45c038eea1f9",
    "createdAt" : "2021-12-12T07:07:15.436485Z",
    "updatedAt" : "2021-12-12T07:07:21.565685Z",
    "name" : "aaa",
    "status" : "confirmed",
    "type" : "translation",
    "submittedAt" : "2021-12-12T07:07:21.564254Z",
    "sourceLanguage" : "en",
    "targetLanguage" : "nl",
    "jobId" : "c181d62c-7a61-4f56-be91-868589cd6b82",
    "archived" : false
  },
  "originalTask" : {
    "id" : "f1b39044-8fb2-4486-9561-45c038eea1f9",
    "createdAt" : "2021-12-12T07:07:15.436485Z",
    "updatedAt" : "2021-12-12T07:07:15.436485Z",
    "name" : "aaa",
    "status" : "pending",
    "type" : "translation",
    "sourceLanguage" : "en",
    "targetLanguage" : "nl",
    "jobId" : "c181d62c-7a61-4f56-be91-868589cd6b82",
    "archived" : false
  }
}
Webhook notification response

The response indicates the resulting status of the delivery. If the delivery has been accepted and processed, the response must have the status code 202 Accepted. Response payload is ignored by LocHub.

If the delivery target is unable to process the request due to exceeding a request rate limit, it should return a 429 Too Many Requests status code and must include the Retry-After header. LocHub will observe the value of the Retry-After header and refrain from sending further requests until the indicated time.

Retry-After supported format 1
Retry-After: 120
Retry-After supported format 2
Retry-After: Wed, 21 Oct 2015 07:28:00 GMT

Any other response (e.g. 200 OK, 400 Bad Request) will be evaluated as an error of the target and will result in a retry of the delivery.

Webhook notification error handling

In case of "failed" delivery of the notification LocHub Orchestrate will retry to deliver it later. An exponential backoff strategy to slowly increase the time between retries is applied. The maximum backoff time is defined as one day.

If an endpoint hasn’t been responding for three days, the endpoint will be marked as broken and LocHub will stop sending requests to this endpoint until it is unblocked. To unblock endpoint TAPICC 1.0.0-beta Webhook API should be used, setting property endpointStatus to ok.

3.4. Other API Operations

The API exposes endpoints to delete any entity mentioned in this guide, which can be used by the creator (or owner) of the entity. An entity owning or referenced by other entities cannot be deleted. For example, to delete a Job the following operation sequence must be observed:

  1. update all Tasks to state cancelled;

  2. delete the Deliverables of the Job;

  3. delete the Inputs of the Job;

  4. delete the Tasks of the Job.

During deletion the Tasks will become ill-defined.

3.5. Alternate Sequences

There various possible scenarios that can be illustrated as alternate use cases. The following diagram describes them at a high level.

diag de442103fd910893981fca48be6c4ecb
Figure 3. Alternate Sequence Diagram

3.6. Task States

The following state transition diagram illustrates the possible states that a Task can have, and the possible transitions.

diag bb722792e6ca51e38126c31cf6dc3ef9
Figure 4. Task State Transition Diagram

Please note that the above diagram does not show the possible transition of Task from completed or completed-with-warnings to confirmed. Even though these transitions are possible, they are discouraged.
In case the result of a Task is unsatisfactory to the content owner, it is instead recommended creating a new Task with the same Inputs - thus making clear the intention of submitting new work, as well as preserving the history of the previous work.