​

Overview of Plugin and Purpose

​

Concepts

​

Userflow

1. Select content for localization
   • In the third party tool we select what content we want to select for localization.
2. In TMS, create a new project
   • We want to create a project, which is a high-level container that groups related work, to store jobs. The project typically defines the scope, context, and configuration.
3. Create job in TMS
   • We create a job via uploading content to TMS.
   • Job is the actual piece of work that is translated. Jobs lives inside projects, get assigned to translators, and are tracked for completion.
4. Run localization on job
   • Vendors / providers are assigned to jobs to perform a workflow.
5. Monitor the progress of the job from the plugin
   • Jobs can be represented as several job part (segments/parts). These parts can be used to see the progress of a job.
6. Export completed job to third party
   • Once jobs reach a completed state, they can be exported. To export the job we need to begin an asynchronous download of the completed job. We then monitor the status of the download until it is ready. Once ready we then download the completed file.
7. Mark job as delivered
   • We then need to update the status of the job to indicate that it has been delivered.

​

Job Lifecycle

1. Creation and initialization
   • File is uploaded to TMS (via file pushed via connector, API call, manual upload, automation), and job is created.
   • Import settings, analysis, and pre-translation is applied here.
   • Status:
     • NEW: if job exists and file is imported successfully.
     • JOB_NOT_READY: if import fails or there is an error on update.
2. Assignment and acceptance
   • Job is assigned to provider / vendor - which gets accepted or declined.
   • Status:
     • NEW: If still unaccepted.
     • ACCEPTED: If vendor has accepted job.
     • DECLINED: If job has been refused.
3. In progress
   • Once accepted, the job moves through the workflow steps configured in the project template.
   • Source updates:
     • If continuous localization is active, the same job can be updated continuously. The job must not be in an error state. Each update overwrites the previous version.
4. Completion and delivery
   • Once the workflow is completed, it will move into completed status.
   • The plugin sets delivered status to confirm it has been exported, or another valid status.
5. Exception outcomes
   • Not all jobs finish successfully.
   • CANCELLED: Work is aborted.
   • REJECTED: The client / reviewer has rejected the output, often requires re-work.

​

Objects and Data Models

​

File Types

​

Plugin Catalogue

​

Canonical Plugin

​

Plugin Catalogue

• A sensible scope for their project.
• What is required vs optional for production.
• A reasonable acceptance criteria to define a production ready plugin.

​

Success Criteria and Business Requirements

​

Prerequisites, for fast development

• Phrase TMS base URL.
• Phrase Authentication credentials for testing and authentication method chosen.
• Delivery definition and definition of done.
• Expected behavior of the plugin - see plugin catalogue.
• Encoding and decoding conventions.
• Supported file types.

​

Testable success criteria

• (Time to) first successful round trip
• Functional minimum
  • Create project, create job, monitor job status, download, update status - all working end to end
  • Locale mapping and validation
• Operational minimum
  • Retry/backoff for transient errors
  • 429 handling
  • Timeout with safe retry mechanics
  • Strong observability and logging
• Security minimum
  • Supported authenticated method
  • Tokens stored securely
  • Least privilege scopes
  • Audit trail of actions

​

How to build

​

Fast Track Path

​

Authentication

• Users must first generate an API token in the User Profile/Access Tokens tab in Phrase Platform Settings page. This token must be stored securely, ideally within a secrets manager / vault. The API token and JWT should not be logged or committed to source control.
• This API token must then be exchanged for a JWT, using the Phrase platform OAuth token endpoint.
  • Endpoint
    • POST /oauth/token
    • Query parameters:
      • grant_type:urn:ietf:params:oauth:grant-type:token-exchange
      • subject_token : API-TOKEN
    • Response:
      • Expected response: 200
        Copy

          {
            "access_token":"GENERATED-JWT",
            "issued_token_type":"urn:ietf:params:oauth:token-type:access_token",
            "token_type":"Bearer",
            "expires_in":14399
          }
        
        • Error response: 400 - includes error code enum and human-readable error description. We should handle the error codes correctly and relay the relevant information to the user.
        Copy

        {
          "error": "enum<string>",
          "error_description": "<string>"
        }
        
  • See documentation for more details.
• This access code should be saved such that we can use the access token in later calls - passing it in the HTTP authorization header in the following format.
  Authorization: Bearer GENERATED-JWT. We should aim to cache the access token and its expiry and automatically attempt to refresh the token when near expiry, and on any 401 (unauthorized response codes)
• When the JWT token expires, we must exchange the token again for a fresh token, we can use the expires_in variable to see how long is left.

​

Pseudocode example

• Method exchangeApiTokenForAccessToken:
  • Makes the API call to exchange the API token for the access token
• Method getAccessToken
  • Checks the cached access token exists and is valid
  • Returns the cached token if valid else it fetches a new access token and returns new token.
• Example API call
  • Example API call that returns 401 response call where we then attempt to refresh the token once.

CACHE = { token: null, expiresAt: 0 }

Function: exchangeApiTokenForAccessToken  
{accessToken, expires_in} = POST /oauth/token
--header 'Content-Type: application/x-www-form-urlencoded'
--data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange'
--data 'subject_token=API-TOKEN'
#Expect 200, else if 400 return error to user
return {accessToken, expires_in}

Function: getAccessToken
now = time.now()
if CACHE.token != null and now < CACHE.expriesAt:
return CACHE.token
{accessToken, expires_in} = exchangeApiTokenForJwt()
cache.TOKEN = accessToken
cache.expiresAt = now + expires_in
return CACHE.TOKEN

# Example request with 401 response  
function authRequest(method, url, **kwargs):  
token = getAccessToken(API_TOKEN)
kwargs.headers = kwargs.headers or {}
kwargs.headers["Authorization"] = "Bearer " + token
resp = HTTP(method, url, **kwargs)
if resp.status == 401:
# token might have expired or was revoked → refresh & retry once
token = exchangeApiTokenForJwt(API_TOKEN).token
CACHE.token = token
CACHE.expiresAt = epoch_seconds() + data.expiresIn
kwargs.headers["Authorization"] = "Bearer " + token
resp = HTTP(method, url, **kwargs)  # single retry
return resp

​

Import Content

• Create a project template
  • We create a project template for projects to standardize the workflow
  • Log into TMS and create a project template
  • Link: TMS page
• Call the API to retrieve the project templates
  • We call this endpoint to retrieve the list of project templates to select the appropriate template for creating a project. We can pass in filters to select the relevant template.
    • Endpoint:
      • GET /api2/v1/projectTemplates
      • Query parameters
        • clientId<Integer>
        • clientName<string>
        • ownerUid<string>
        • domainName<string>
      • Response: Expect 200 response with pagination of project templates
        Copy

          {
            "totalElements": 123,
            "totalPages": 123,
            "pageSize": 123,
            "pageNumber": 123,
            "numberOfElements": 123,
            "content": [
              {
                "templateName": "<string>",
                "sourceLang": "<string>",
                "targetLangs": [
                  "<string>"
                ],
                "id": "<string>",
                "uid": "<string>",
                "owner": {
                  "firstName": "<string>",
                  "lastName": "<string>",
                  "userName": "<string>",
                  "email": "<string>",
                  "role": "SYS_ADMIN",
                  "id": "<string>",
                  "uid": "<string>"
                },
                "createdBy": {
                  "firstName": "<string>",
                  "lastName": "<string>",
                  "userName": "<string>",
                  "email": "<string>",
                  "role": "SYS_ADMIN",
                  "id": "<string>",
                  "uid": "<string>"
                },
                "dateCreated": "2023-11-07T05:31:56Z",
                "domain": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                },
                "subDomain": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                },
                "costCenter": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                },
                "businessUnit": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                },
                "projectWorkflowSettings": {
                  "propagateTranslationsToLowerWfDuringUpdateSource": true
                },
                "workflowSteps": [
                  {
                    "name": "<string>",
                    "id": "<string>",
                    "uid": "<string>",
                    "order": 123,
                    "lqaEnabled": true
                  }
                ],
                "note": "<string>",
                "client": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                }
              }
            ],
            "sort": {
              "orders": [
                {
                  "direction": "ASC",
                  "property": "<string>"
                }
              ]
            }
          }
        
  • Documentation
• Create a project from a template
  • This endpoint is used to create a project - we pass the templateUid in as a path parameter to create the project with a template. We must give the name variable in the body. This endpoint then returns the the ProjectDto, which is an object representing the project.
    • Endpoint:
    • POST /api2/v2/projects/applyTemplate/{templateUid}
    • Path: templateUid <String>
    • Body: REQUIRED name<string>
      Copy

        {
          "name": "<string>",
          "sourceLang": "<string>",
          "targetLangs": [
            "<string>"
          ],
          "workflowSteps": [
            {
              "id": "<string>"
            }
          ],
          "dateDue": "2023-11-07T05:31:56Z",
          "note": "<string>",
          "client": {
            "id": "<string>"
          },
          "businessUnit": {
            "id": "<string>"
          },
          "domain": {
            "id": "<string>"
          },
          "subDomain": {
            "id": "<string>"
          },
          "costCenter": {
            "id": "<string>"
          }
        }
      
    • Response: Expect 201 response with ProjectDto
      Copy

        {
          "uid": "<string>",
          "internalId": 123,
          "id": "<string>",
          "name": "<string>",
          "dateCreated": "2023-11-07T05:31:56Z",
          "domain": {
            "id": "<string>",
            "uid": "<string>",
            "name": "<string>"
          },
          "subDomain": {
            "id": "<string>",
            "uid": "<string>",
            "name": "<string>"
          },
          "owner": {
            "firstName": "<string>",
            "lastName": "<string>",
            "userName": "<string>",
            "email": "<string>",
            "role": "SYS_ADMIN",
            "id": "<string>",
            "uid": "<string>"
          },
          "sourceLang": "<string>",
          "targetLangs": [
            "<string>"
          ],
          "references": [
            {
              "id": "<string>",
              "uid": "<string>",
              "filename": "<string>",
              "note": "<string>",
              "dateCreated": "2023-11-07T05:31:56Z",
              "createdBy": {
                "firstName": "<string>",
                "lastName": "<string>",
                "userName": "<string>",
                "email": "<string>",
                "role": "SYS_ADMIN",
                "id": "<string>",
                "uid": "<string>"
              }
            }
          ],
          "mtSettingsPerLanguageList": [
            {
              "targetLang": "<string>",
              "machineTranslateSettings": {
                "id": "<string>",
                "uid": "<string>",
                "name": "<string>",
                "type": "<string>"
              }
            }
          ],
          "status": "NEW",
          "userRole": "<string>"
        }
      
    • Documentation
• Create job
  • API call to create a job where the source file can be in the message body or downloaded from the connector.
  • Endpoint:
    • POST /api2/v1/projects/{projectUid}/jobs
    • Path: projectUid <String>
    • Body: source file (optional)
    • Response: Expect 200 response with Jobs[] and asyncRequest object
      Copy

          {
            "unsupportedFiles": [
              "<string>"
            ],
            "jobs": [
              {
                "uid": "<string>",
                "status": "NEW",
                "providers": [
                  {
                    "type": "<string>",
                    "id": "<string>",
                    "uid": "<string>"
                  }
                ],
                "targetLang": "<string>",
                "workflowLevel": 123,
                "workflowStep": {
                  "name": "<string>",
                  "id": "<string>",
                  "uid": "<string>",
                  "order": 123,
                  "lqaEnabled": true
                },
                "filename": "<string>",
                "dateDue": "2023-11-07T05:31:56Z",
                "dateCreated": "2023-11-07T05:31:56Z",
                "updateSourceDate": "2023-11-07T05:31:56Z",
                "imported": true,
                "jobAssignedEmailTemplate": {},
                "notificationIntervalInMinutes": 123,
                "continuous": true,
                "sourceFileUid": "<string>"
              }
            ],
            "asyncRequest": {
              "id": "<string>",
              "dateCreated": "2023-11-07T05:31:56Z",
              "action": "PRE_ANALYSE"
            }
          }
      
    • Documentation

​

Pseudocode example

#Call API for project templates
projectTemplates[] = GET /api2/v1/projectTemplates 
					-H "Authorization: Bearer accessToken"
					# Expect 200 response, handle 4xx and 5xx errors

if projectTemplates.isEmpty()
	throw new NotFoundException

# Find projectTemplateUid
projectTemplateUid = projectTemplates.findSuitableTemplate().getUid()

#Create project
projectDto = POST /projects/applyTemplate/{templateUid}
			-H "Authorization: Bearer accessToken"
			-d { name, sourceLanguage, targetLanguages }
			# Expect 201 response, handle 4xx and 5xx errors
			
projectUid = projectDto.getUid

#Create job
jobDto = POST /api2/v1/projects/{projectUid}/jobs
		-H "Authorization: Bearer accessToken"
		-d {content}
		# Expect 201 response, handle 4xx and 5xx errors
		
# Persist jobUid

​

Monitor Job progress

• List job parts status
• Call endpoint to check the status of each job part. Returns the statuses of each part of the job. There are other options for monitoring job progress however for simplicity we use job parts for the fast track method.
• For the fast track implementation we should implement a simple polling system that sleeps in between calls.
• Endpoint:
  • GET /api2/v1/projects/{projectUid}/jobs/{jobUid}/parts
  • Path:
    • projectUid<string>
    • jobUid<string>
  • Response: Expect 200 with PageDto of JobParts
    Copy

      {
          "sort": null,
          "pageNumber": 0,
          "content": [
              {
                  "remoteFile": {
                      "encodedFolder": "",
                      "humanReadableFileName": "",
                      "encodedFileName": "",
                      "humanReadableFolder": ""
                  },
                  "importStatus": {
                      "status": "",
                      "errorMessage": 
                  },
                  "workflowStep": ,
                  "imported": ,
                  "dateCreated": "",
                  "serverTaskId": "",
                  "dateDue": ,
                  "targetLang": "",
                  "continuous": ,
                  "originalFileDirectory": ,
                  "innerId": "",
                  "owner": {
                      "userName": "",
                      "uid": "",
                      "id": "",
                      "firstName": "",
                      "lastName": "",
                      "role": "",
                      "email": ""
                  },
                  "uid": "",
                  "status": "",
                  "filename": "",
                  "split": ,
                  "sourceFileUid": "",
                  "providers": []
              }
          ],
          "numberOfElements": ,
          "totalElements": ,
          "pageSize": ,
          "totalPages": 
      }
    

​

Pseudocode example

while (time < timeout)
	jobParts[] = GET /jobs/{jobUid}/parts
				-H "Authorization: Bearer accessToken"
				# Expect 200, else attempt retry
	if all jobParts in [COMPLETED]
		return job completed
	elif all jobParts in [FAILED, REJECTED, CANCELLED]
		return job failed
	sleep exponential_backoff_with_jitter_time

​

Exporting

• Initiate async download of a target file.
  • Given the project and job uids, we initiate the download a target file - this endpoint returns an async request which we can use to monitor the status of the operation, and download the file given the async request id.
    • We must persist the asyncRequestID as this is used to perform the download operation.
    • See Recipe for asynchronous requests for more information
• Alternatively, we can pass, an optional, callbackUrl in the body - which will get a notification when the operation is completed.
• Endpoint:
  • PUT /api2/v3/projects/{projectUid}/jobs/{jobUid}/targetFile
  • Path:
  • projectUid<String>
  • jobUid<String>
  • Body: (optional)
    Copy

      {
        "callbackUrl": "<string>"
      } 
    
  • Response: Expect 202 response with AsyncRequest object
    Copy

        {
          "asyncRequest": {
            "id": "<string>",
            "createdBy": {
              "firstName": "<string>",
              "lastName": "<string>",
              "userName": "<string>",
              "email": "<string>",
              "role": "SYS_ADMIN",
              "id": "<string>",
              "uid": "<string>"
            },
            "dateCreated": "2023-11-07T05:31:56Z",
            "action": "PRE_ANALYSE",
            "asyncResponse": {
              "dateCreated": "2023-11-07T05:31:56Z",
              "errorCode": "<string>",
              "errorDesc": "<string>",
              "errorDetails": [
                {
                  "code": "<string>",
                  "args": {},
                  "message": "<string>"
                }
              ],
              "warnings": [
                {
                  "code": "<string>",
                  "args": {},
                  "message": "<string>"
                }
              ]
            },
            "parent": "<unknown>",
            "project": {
              "uid": "<string>",
              "name": "<string>"
            }
          },
          "reference": {
            "uid": "<string>",
            "type": "JOB"
          }
        }
    
  • Documentation
• Download the target file based on an async request.
  • After we confirm the previous operation is complete - we then can download the target file.
  • This call will return the target file with translations.
  • NOTE: the asyncRequestID can only be used once.
  • Endpoint:
    • GET /api2/v2/projects/{projectUid}/jobs/{jobUid}/downloadTargetFile/{asyncRequestId}
    • Path:
      • projectUid<string>
      • jobUid<string>
      • asyncRequestId<string>
    • Query parameters: format: ORIGINAL or PDF
    • Response: Expect 200 response with application/octet-stream
    • Documentation
• Edit job status
  • We call this endpoint to mark the job as delivered to indicate that the job has been successfully retrieved.
  • Endpoint
    • POST /api2/v1/projects/{projectUid}/jobs/{jobUid}/setStatus
    • Path:
      • projectUid<string>
      • jobUid<string>
    • Body: requestedStatus: The new job status. notifyOwner: A flag to notify
      Copy

          {
              "requestedStatus": "NEW",
              "notifyOwner": true,
              "propagateStatus": true
          }
      
    • Response: Expect 204 response
    • Documentation

​

Pseudocode example

# Initiate async download
asyncRequest = PUT /api2/v3/projects/{projectUid}/jobs/{jobUid}/targetFile
				-H "Authorization: Bearer accessToken"
				#Expect 202 response, handle 4xx, 5xx responses accordingly
			
# Monitor asyncRequest status
while (time < timeout)
	Optional asyncResponse GET /api2/v1/async/{asyncRequestId}
	if asyncResponse null
		sleep exponential_backoff_with_jitter_time 
	if asyncReponse.errorDetails not null
		throw exception
	return asyncResponse

# Download async target file

content = GET /api2/v2/projects/{projectUid}/jobs/{jobUid}/downloadTargetFile/{asyncRequestId}
-H "Authorization: Bearer accessToken"
#Expect 202 response, handle 4xx, 5xx responses accordingly

persist content()
mapTo3rdPartySystem()

# Update job status
POST /api2/v1/projects/{projectUid}/jobs/{jobUid}/setStatus
-H "Authorization: Bearer accessToken"
-d {"requestedStatus": "DELIVERED"}
#Expect 200 response, handle 4xx, 5xx responses accordingly

​

Fast Track checklist success criteria

• A user can select content in a third party system.
• The plugin can create a plugin in TMS project, using a template.
• The plugin can upload source files and create a job within a project.
• The plugin can monitor the job status to check for when it is complete.
• The plugin can download the translated file.
• The plugin can commit the localized content into the third party system.
• The plugin is able to mark the job as DELIVERED status.

​

Golden path (Production ready)

​

Building The Golden Path Plugin

​

Authentication

• Users must first generate an API token in the User Profile/Access Tokens tab in Phrase Platform Settings page.
• Using the generated API token it must then be exchanged for a JWT, using the Phrase platform OAuth token endpoint.
• Endpoint
  • POST /oauth/token
  • Query parameters:
    • grant_type:urn:ietf:params:oauth:grant-type:token-exchange
    • subject_token : API-TOKEN
  • Response:
    • Expected response: 200
      Copy

      {
        "access_token":"GENERATED-JWT",
        "issued_token_type":"urn:ietf:params:oauth:token-type:access_token",
        "token_type":"Bearer",
        "expires_in":14399 
      }
      
    • Error response: 400 - includes error code enum and human readable error description. We should handle the error codes correctly and relay the information to the user.
      Copy

      {
        "error": "enum<string>",
        "error_description": "<string>"
      }
      
  • See documentation for more details.
• This access code should be saved such that we can use the access token in later calls - passing it in the HTTP authorization header in the following format.
  Authorization: Bearer GENERATED-JWT. We should aim to cache the access token and its expiry and automatically attempt to refresh the token when near expiry, and on any 401 (unauthorized response codes)
• When the JWT token expires, we must exchange the token again for a fresh token, we can use the expires_in variable to see how long is left.

​

Create a Project

• Create a project template
  • We create a project template for projects to standardise the workflow
  • This also allows us to apply a template when creating a project and reduces the amount of fields that we need to determine when creating a project from scratch
  • Log into TMS and create a project template
  • Link: TMS page
• Call the API to retrieve the project templates
  • We call this endpoint to retrieve the list of project templates to select the appropriate template. We can also pass in specific filters in order to find the correct template.
  • We need to persist the TemplateUid of the selected template.
  • Endpoint:
    • GET /api2/v1/projectTemplates
    • Query parameters
      • clientId<Integer>
      • clientName<string>
      • ownerUid<string>
      • domainName<string>
    • Response: Expect 200 response with pagination of project templates
      Copy

          {
            "totalElements": 123,
            "totalPages": 123,
            "pageSize": 123,
            "pageNumber": 123,
            "numberOfElements": 123,
            "content": [
              {
                "templateName": "<string>",
                "sourceLang": "<string>",
                "targetLangs": [
                  "<string>"
                ],
                "id": "<string>",
                "uid": "<string>",
                "owner": {
                  "firstName": "<string>",
                  "lastName": "<string>",
                  "userName": "<string>",
                  "email": "<string>",
                  "role": "SYS_ADMIN",
                  "id": "<string>",
                  "uid": "<string>"
                },
                "createdBy": {
                  "firstName": "<string>",
                  "lastName": "<string>",
                  "userName": "<string>",
                  "email": "<string>",
                  "role": "SYS_ADMIN",
                  "id": "<string>",
                  "uid": "<string>"
                },
                "dateCreated": "2023-11-07T05:31:56Z",
                "domain": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                },
                "subDomain": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                },
                "costCenter": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                },
                "businessUnit": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                },
                "projectWorkflowSettings": {
                  "propagateTranslationsToLowerWfDuringUpdateSource": true
                },
                "workflowSteps": [
                  {
                    "name": "<string>",
                    "id": "<string>",
                    "uid": "<string>",
                    "order": 123,
                    "lqaEnabled": true
                  }
                ],
                "note": "<string>",
                "client": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>"
                }
              }
            ],
            "sort": {
              "orders": [
                {
                  "direction": "ASC",
                  "property": "<string>"
                }
              ]
            }
          }
      
    • Documentation
• Create a project from a template
  • This endpoint is used to create a project - we pass the templateUid in as a path parameter to create the project with a template. We must give the name variable in the body. This endpoint then returns the the ProjectDto, which is an object representing the project.
  • Validate the returned ProjectDto to confirm is as expected.
  • We need to persist the created ProjectUid.
  • Endpoint:
    • POST /api2/v2/projects/applyTemplate/{templateUid}
    • Path: templateUid <String>
    • Body: (Required) name<string>
      Copy

          {
            "name": "<string>",
            "sourceLang": "<string>",
            "targetLangs": [
              "<string>"
            ],
            "workflowSteps": [
              {
                "id": "<string>"
              }
            ],
            "dateDue": "2023-11-07T05:31:56Z",
            "note": "<string>",
            "client": {
              "id": "<string>"
            },
            "businessUnit": {
              "id": "<string>"
            },
            "domain": {
              "id": "<string>"
            },
            "subDomain": {
              "id": "<string>"
            },
            "costCenter": {
              "id": "<string>"
            }
          }
      
    • Response: Expect 201 response with ProjectDto
      Copy

          {
            "uid": "<string>",
            "internalId": 123,
            "id": "<string>",
            "name": "<string>",
            "dateCreated": "2023-11-07T05:31:56Z",
            "domain": {
              "id": "<string>",
              "uid": "<string>",
              "name": "<string>"
            },
            "subDomain": {
              "id": "<string>",
              "uid": "<string>",
              "name": "<string>"
            },
            "owner": {
              "firstName": "<string>",
              "lastName": "<string>",
              "userName": "<string>",
              "email": "<string>",
              "role": "SYS_ADMIN",
              "id": "<string>",
              "uid": "<string>"
            },
            "sourceLang": "<string>",
            "targetLangs": [
              "<string>"
            ],
            "references": [
              {
                "id": "<string>",
                "uid": "<string>",
                "filename": "<string>",
                "note": "<string>",
                "dateCreated": "2023-11-07T05:31:56Z",
                "createdBy": {
                  "firstName": "<string>",
                  "lastName": "<string>",
                  "userName": "<string>",
                  "email": "<string>",
                  "role": "SYS_ADMIN",
                  "id": "<string>",
                  "uid": "<string>"
                }
              }
            ],
            "mtSettingsPerLanguageList": [
              {
                "targetLang": "<string>",
                "machineTranslateSettings": {
                  "id": "<string>",
                  "uid": "<string>",
                  "name": "<string>",
                  "type": "<string>"
                }
              }
            ],
            "status": "NEW",
            "userRole": "<string>"
          }
      
  • Documentation

​

Upload Preview Package (Optional)

​

Import Content

• Create job
  • This is an API call to create a job within a project. We must provide the projectUid in the path and the source file can be in message body or downloaded from connector.
  • This call returns the Jobs object and an asyncRequest object.
    • See monitoring job progress and the recipe for asynchronous request for how to handle the asyncResponse.
  • From the Jobs object we want to persist the (job)uid – this would allow us to perform further actions on the job.
  • NOTE: We can pass in a callback URL to receive a notification on the job status. This is different to the webhooks that can be set up globally.
  • NOTE: If using the live preview feature, we want to include the file id here too.
    • jobPreviewPackageFileUidRef in the Memsource header.
    • See the recipe fore live preview for further information.
  • NOTE: If using the continuous updating feature we want to include the flag.
    • See the recipe for continuous updates for further information.
  • Endpoint:
    • POST /api2/v1/projects/{projectUid}/jobs
    • Path: projectUid <String>
    • Body: source file (optional)
    • Response: Expect 200 response with Jobs[] and asyncRequest object
      Copy

          {
            "unsupportedFiles": [
              "<string>"
            ],
            "jobs": [
              {
                "uid": "<string>",
                "status": "NEW",
                "providers": [
                  {
                    "type": "<string>",
                    "id": "<string>",
                    "uid": "<string>"
                  }
                ],
                "targetLang": "<string>",
                "workflowLevel": 123,
                "workflowStep": {
                  "name": "<string>",
                  "id": "<string>",
                  "uid": "<string>",
                  "order": 123,
                  "lqaEnabled": true
                },
                "filename": "<string>",
                "dateDue": "2023-11-07T05:31:56Z",
                "dateCreated": "2023-11-07T05:31:56Z",
                "updateSourceDate": "2023-11-07T05:31:56Z",
                "imported": true,
                "jobAssignedEmailTemplate": {},
                "notificationIntervalInMinutes": 123,
                "continuous": true,
                "sourceFileUid": "<string>"
              }
            ],
            "asyncRequest": {
              "id": "<string>",
              "dateCreated": "2023-11-07T05:31:56Z",
              "action": "PRE_ANALYSE"
            }
          }
      
  • Documentation

• List: Firstly, the list endpoint - a GET endpoint that should list all content that can be exported to TMS and formatted in any relevant directories, given the correct credentials.
  This endpoint should handle multiple error cases and respond with the correct response codes.
• Download: The download endpoint - a GET endpoint given the id of a specific content should trigger the downloading process of the content. The download process should encode the content to a suitable format for uploading to TMS and return this content within the response body.
  This endpoint should handle multiple error cases and respond with the correct respond codes.

​

Optional: Assign Providers and Analysis

​

Monitor Job Progress

• From the Settings page on TMS, scroll down to the Integrations section and click on Webhooks.
• From here we can add a new Webhook.
• Provide a name, URL and security token if required.
  Specify a value to be included in either the x-memsource-token header or the Authorization header that allows the user to choose their preferred method for authenticating the webhook sender.
• Select events.
• Click Preview schema to view the webhook response when running.
• Click Create webhook.
• The webhook is added to the list on the Webhooks page.
• We can then subscribe to this web hook and monitor it for any job status change events.

• Authenticate / verify the incoming request (token / header).
• Store the webhook event, we should aim to prevent duplicate deliveries that can be achieved by storing against a unique constraint.
• Respond with 200 response for ACK response after persisting event - this confirms to the Phrase that the event was received.
• Then we want to process the event - ideally we do this by adding the webhook event to an async processing queue.

​

Pseudocode example

function handleWebHook(Event event)
  verifyWebhook(event)
  storeEvent(event)
  eventMessage = createEventMessage(event)
  asyncProcessingQueue.push(eventMessage)
  return HttpStatus.200

• 4xx / 5xx rates
• Duplicate event rates
• Rate of using fallback for finding event updates.
• (If you are using async processing of webhook events) queue depth and worker error rates

​

Exporting

• As found in the fast track section.
• Initiate async download of target file
  • Given the project and job uids we initiate the download a target file - this endpoint returns an async request which we can use to monitor the status of the operation, and download the file given the async request id.
    • We must persist the asyncRequestID as this is used to perform the download operation.
    • See Recipe for asynchronous requests for more information.
• Alternatively, we can pass, an optional, callbackUrl in the body - which will get a notification when the operation is completed.
• Endpoint:
  • PUT /api2/v3/projects/{projectUid}/jobs/{jobUid}/targetFile
    • Path:
      • projectUid<String>
      • jobUid<String>
    • Body: (optional)
      Copy

      {
         "callbackUrl":
      }
      
  • Response: Expect 202 response with AsyncRequest object
    Copy

    {
      "asyncRequest": {
        "id": "<string>",
        "createdBy": {
          "firstName": "<string>",
          "lastName": "<string>",
          "userName": "<string>",
          "email": "<string>",
          "role": "SYS_ADMIN",
          "id": "<string>",
          "uid": "<string>"
        },
        "dateCreated": "2023-11-07T05:31:56Z",
        "action": "PRE_ANALYSE",
        "asyncResponse": {
          "dateCreated": "2023-11-07T05:31:56Z",
          "errorCode": "<string>",
          "errorDesc": "<string>",
          "errorDetails": [
            {
              "code": "<string>",
              "args": {},
              "message": "<string>"
            }
          ],
          "warnings": [
            {
              "code": "<string>",
              "args": {},
              "message": "<string>"
            }
          ]
        },
        "parent": "<unknown>",
        "project": {
          "uid": "<string>",
          "name": "<string>"
        }
      },
      "reference": {
        "uid": "<string>",
        "type": "JOB"
      }
    }
    
    • Documentation
• Download the target file based on an async request
  • After we confirm the previous operation is complete - we then can download the target file.
  • This call will return the target file with translations.
  • NOTE: the asyncRequestID can only be used once.
  • Endpoint:
    • GET /api2/v2/projects/{projectUid}/jobs/{jobUid}/downloadTargetFile/{asyncRequestId}
    • Path:
      • projectUid<string>
      • jobUid<string>
      • asyncRequestId<string>
    • Query parameters: format: ORIGINAL or PDF
    • Response: Expect 200 response with application/octet-stream
    • Documentation

• This method requires us to expose an endpoint that can be called from TMS for handling importing content.
• This should be a POST endpoint which can be called with the correct identifiers and content.
• The logic of this endpoint should also be handle to handle the exporting process in the third party system - if a decoding processing is required.

• We call this endpoint to mark the job as delivered to indicate that the job has been successfully retrieved.
  • Endpoint
    • POST /api2/v1/projects/{projectUid}/jobs/{jobUid}/setStatus
    • Path:
      • projectUid<string>
      • jobUid<string>
    • Body: requestedStatus: The new job status. notifyOwner: A flag to notify
      Copy

          {
              "requestedStatus": "NEW",
              "notifyOwner": true,
              "propagateStatus": true
          }
      
    • Response: Expect 204 response
    • Documentation

​

Plugin Variants

​

Canonical Plugin (general-purpose)

​

Updating Live Content Plugin

​

Continuous Localisation

​

Error Handling

• Retry mechanism for transient HTTP errors (429, 5xx).
  • These responses should be retried with exponential backoff and jitter.
  • Phrase API has a request limit of 6000 requests per minute for logged-in users, for further information about API rate limits see the documentation.
• 4xx validation errors should be related to the end user with actionable messages.
• 5xx errors should be logged with the relevant error codes and messages. These cases should be handled gracefully and the user should be informed of the error.
• Add idempotency to avoid duplicate actions.
• Add alerting on repeat failures.

​

Documentation and Testing Requirements

​

Documentation

• An overview of the architecture.
• How it has implemented the canonical lifecycle.
• Error handling.
• Observability.
• Security methods.
• Data models.
• Versioning & Compatibility Policy.

​

Testing

• Happy path.
  • Single file, single locale.
  • Large file or multiple target languages.
  • Life cycle transition tests.
  • Key user flows like creating a project, creating a job, monitoring progress, etc.
• Error handling.
  • HTTP errors.
  • Validation errors.
  • Internal errors.
• Security.
• Failure cases.
  • Authentication issues.
  • Download issues.
  • Idempotency tests if applicable.
• Common pitfall cases
  • 401/403: invalid token / permissions.
  • 429: rate limit hit.
• Webhook failure cases.

​

Logging and Observability Requirements

• Timestamps.
• Request id.
• Correlation id.
• Project uid.
• Job uid.
• Plugin instance id.
• Endpoint details, HTTP method, responses status, duration.
• Phrase action id.

• Job creation success rate.
• Average job creation latency.
• Export / import durations.
• 5xx error rates.

​

Recipes / Additional Features Guide

​

Live Preview

​

HTML File for Localization

• When creating a job in TMS, you have to specify the file format that you want to localize. If you choose HTML and upload HTML for localization, it will be rendered as a live preview in the editor. This is not necessarily possible for all CMSs as they often organize content into fields that they represent in complicated data structures which would be challenging to convert to HTML and then back.

​

Upload a Preview Reference Package When Creating a Job

• Create a ZIP file with assets (images, CSS, JS) and a single HTML which will be rendered by the editor.
  • The HTML needs to have the assets linked as relative links.
  • Absolute links (https://google.com) and assets linked in this way will be preserved but may not work correctly. This is intended to work around the issue of assets being unavailable via the Internet or requiring authentication for access.
• Call the following endpoint to upload the preview package. We need to pass the projectUid as a path parameter and the preview package file as the body contents.
• The endpoint returns the uId of the uploaded preview package.
• Endpoint:
  • POST /api2/v1/projects/{projectUid}/jobPreviewPackage
  • Path: projectUid <String>
  • Body: Required: file<file>
  • Response: Expect 201 Response
    Copy

        {
          "uid": "<string>",
          "fileUid": "<string>",
          "fileName": "<string>",
          "organizationRef": {
            "uid": "<string>",
            "name": "<string>"
          },
          "projectUidRef": {
            "uid": "<string>"
          },
          "taskId": "<string>",
          "jobUidRef": {
            "uid": "<string>"
          },
          "createdByRef": {
            "firstName": "<string>",
            "lastName": "<string>",
            "userName": "<string>",
            "email": "<string>",
            "role": "SYS_ADMIN",
            "id": "<string>",
            "uid": "<string>"
          },
          "dateCreated": "2023-11-07T05:31:56Z"
        }
    
  • Documentation
• When creating the job using the Create Job endpoint (reference), add the id from the previous step as a parameter jobPreviewPackageFileUidRef in the Memsource header. Once the job is created, it should have a live preview created and visible in the editor.

​

Asynchronous Request

​

Polling

• Endpoint
  • GET /api2/v1/async/{asyncRequestId}
  • Path: asyncRequestId <int>
  • Response:
    Copy

    {
      "id": "<string>",
      "createdBy": {
        "firstName": "<string>",
        "lastName": "<string>",
        "userName": "<string>",
        "email": "<string>",
        "role": "SYS_ADMIN",
        "id": "<string>",
        "uid": "<string>"
      },
      "dateCreated": "2023-11-07T05:31:56Z",
      "action": "PRE_ANALYSE",
      "asyncResponse": {
        "dateCreated": "2023-11-07T05:31:56Z",
        "errorCode": "<string>",
        "errorDesc": "<string>",
        "errorDetails": [
          {
            "code": "<string>",
            "args": {},
            "message": "<string>"
          }
        ],
        "warnings": [
          {
            "code": "<string>",
            "args": {},
            "message": "<string>"
          }
        ],
        "acceptedSegmentsCount": 123
      },
      "parent": "<unknown>",
      "project": {
        "uid": "<string>",
        "name": "<string>"
      }
    }
    
  • Documentation

#Polling asyncRequest

#Create job (example async API)
{jobDto, asyncRequest} = POST /api2/v1/projects/{projectUid}/jobs
		-H "Authorization: Bearer accessToken"
		-d {content}
		# Expect 201 response, handle 4xx and 5xx errors

#Poll async status
while (time < timeout)
	Optional asyncResponse GET /api2/v1/async/{asyncRequestId}
	if asyncResponse null
		sleep exponential_backoff_with_jitter_time
	if asyncReponse.errorDetails not null
		throw exception
	return asyncResponse

​

Callback

• Information about the asynchronous request (the same as when calling getAsyncRequest).
• Detailed information about the result of the action, such as a full analysis or job details.

{
   "asyncRequest": {
       ...
  }
 "analyse": {
   ...
  }
}

​

Pseudocode example

#Callback method
#Create job (example async API)
jobDto = POST /api2/v1/projects/{projectUid}/jobs
		-H "Authorization: Bearer accessToken"
		-d {content, callbackURL}
		# Expect 201 response, handle 4xx and 5xx errors


#Callback endpoint
@PostMethod
callbackMethod(String bodyJson){
	asyncResponse = parse(bodyJson, AsyncResponse.class)
	handle(asyncResponse)
	returns 200
}

​

Assign Providers

• Endpoint:
  • POST /api2/v1/projects/{projectUid}/applyTemplate/{templateUid}/assignProviders
  • Path:
    • templateUid <String>
    • projectUid <String>
  • Response: Expect 200 response
    Copy

    {
      "jobs": [
        {
          "uid": "<string>",
          "status": "NEW",
          "providers": [
            {
              "type": "<string>",
              "id": "<string>",
              "uid": "<string>"
            }
          ],
          "targetLang": "<string>",
          "workflowLevel": 123,
          "workflowStep": {
            "name": "<string>",
            "id": "<string>",
            "uid": "<string>",
            "order": 123,
            "lqaEnabled": true
          },
          "filename": "<string>",
          "dateDue": "2023-11-07T05:31:56Z",
          "dateCreated": "2023-11-07T05:31:56Z",
          "updateSourceDate": "2023-11-07T05:31:56Z",
          "imported": true,
          "jobAssignedEmailTemplate": {},
          "notificationIntervalInMinutes": 123,
          "continuous": true,
          "sourceFileUid": "<string>"
        }
      ]
    }
    
• Documentation

​

Analysis

• Endpoint:
  • POST /api2/v1/analyses/byProviders
  • Body:
  • Required: jobs[]
    Copy

    {
      "jobs": [
        {
          "uid": "<string>"
        }
      ],
      "type": "PreAnalyse",
      "includeFuzzyRepetitions": true,
      "separateFuzzyRepetitions": true,
      "includeConfirmedSegments": true,
      "includeNumbers": true,
      "includeLockedSegments": true,
      "countSourceUnits": true,
      "includeTransMemory": true,
      "includeNonTranslatables": true,
      "includeMachineTranslationMatches": true,
      "transMemoryPostEditing": true,
      "nonTranslatablePostEditing": true,
      "machineTranslatePostEditing": true,
      "name": "<string>",
      "netRateScheme": {
        "id": "<string>"
      },
      "compareWorkflowLevel": 8,
      "useProjectAnalysisSettings": true,
      "callbackUrl": "<string>"
    }
    
  • Response: Expect 200 response
    Copy

    {
      "analyses": [
        {
          "asyncRequest": {
            "id": "<string>",
            "createdBy": {
              "firstName": "<string>",
              "lastName": "<string>",
              "userName": "<string>",
              "email": "<string>",
              "role": "SYS_ADMIN",
              "id": "<string>",
              "uid": "<string>"
            },
            "dateCreated": "2023-11-07T05:31:56Z",
            "action": "PRE_ANALYSE",
            "asyncResponse": {
              "dateCreated": "2023-11-07T05:31:56Z",
              "errorCode": "<string>",
              "errorDesc": "<string>",
              "errorDetails": [
                {
                  "code": "<string>",
                  "args": {},
                  "message": "<string>"
                }
              ],
              "warnings": [
                {
                  "code": "<string>",
                  "args": {},
                  "message": "<string>"
                }
              ],
              "acceptedSegmentsCount": 123
            },
            "parent": "<unknown>",
            "project": {
              "uid": "<string>",
              "name": "<string>"
            }
          },
          "analyse": {}
        }
      ]
    }
    
  • Documentation

​

Notifications

• Endpoint:
  • POST /api2/v1/projects/{projectUid}/jobs/notifyAssigned
  • Path parameters: projectUid <String>
  • Body:
    Copy

    {
      "jobs": [
        {
          "uid": "<string>"
        }
      ],
      "emailTemplate": {
        "id": "<string>"
      },
      "cc": [
        "<string>"
      ],
      "bcc": [
        "<string>"
      ]
    }
    
  • Response: 204 is successful case
  • Documentation

​

Continuous Updates

​

Why we want this

​

How to build

• Create logic to monitor content for changes.
• Call the following Phrase endpoint. We need to provide the projectUid in the path and the file name in the Content-Disposition header. We provide the job file directly in the body. We can must also provide metadata - the jobUids reference and any optional settings. Note: see documentation of endpoint to see job restrictions and additional settings.
• Endpoint
  • POST /projects/{projectUid}/jobs/source
  • Headers: Content-Disposition <String>
  • Path: projectUid <String>
  • Body: file<object>
    • Metadata
      Copy

      {
        "jobs": [
          {
              "uid": "jobIn1stWfStepAndNonFinalStatusUid"
          }
        ],
        "preTranslate": false,
        "allowAutomaticPostAnalysis": false
        "callbackUrl": "https://my-shiny-service.com/consumeCallback"
      }
      
  • Response: Expect 200
    Copy

    {
      "asyncRequest": {
        "id": "<string>",
        "dateCreated": "2023-11-07T05:31:56Z",
        "action": "PRE_ANALYSE"
      },
      "jobs": [
        {
          "uid": "<string>",
          "status": "NEW",
          "targetLang": "<string>",
          "filename": "<string>",
          "workflowLevel": 123,
          "workflowStep": {
            "name": "<string>",
            "id": "<string>",
            "uid": "<string>",
            "order": 123,
            "lqaEnabled": true
          }
        }
      ]
    }
    
  • Documentation
• We can view the status of the job in multiple ways.
  • Callback url - we can set a callback url in the metadata and listen for the call back.
  • Asynchronous request - response includes an asynchronous request which we can monitor using the API to check if the job is complete
    • See the recipe for handling asynchronous requests.
  • Webhook - we can set up a webhook to receive updates and listen for the completed job
    • See golden path, monitoring job progress for more information..
• After the job is completed, we want to download the new file
• Listen to TMS Web hook for when the job is done, and download a new file. When the job is complete, we then download the target file and commit it.

​

Reporting

• To help us provide reporting on the impact and value that your Plugin provides our customers please consider adding the following. While using the plugin to call TMS endpoint POST /api2/v1/projects/$project\_id/jobsfor creating a job. As a part of the Memsource header, you can append a sourceData object to the JSON:

{
  "targetLangs": [
    "de"
  ],
  "sourceData": {
    "clientType": "MY_PLUGIN",
    "clientVersion": "1.2.4",
    "hostVersion": "4.5.2"
  }
}

​

Idempotency

• Creating a project
• Uploading a file
• Creating a job
• Exporting a job
• Updating a job status

​

Additional Resources

• Postman collection. A postman collection has been created with all the relevant requests to the Phrase API with headers and example payloads. Developers can use this as a sandbox for validation, testing, and learning about the API. Additionally, this should also serve as a reference point for the API when developing the plugin.

​

Reference Appendix

​

Glossary

​

Endpoint Glossary

​

Error Codes