Build a New Translation Connector

To build a new translation connector as a RESTful service, a developer needs to implement the RESTful interfaces provided by the connector framework.

The Oracle Content Management Cloud connector framework has the following interfaces:

APIResource Interface: This interface is the starting point of the translation connector. You simply return the version that's supported.
ServerResource Interface: When an administrator or developer registers a translation connector in the Oracle Content Management (OCM) server, OCM calls this service to get the basic details about the connector server, such as the authorization type, custom fields, and properties for the translation connector:
- Authorization types:
  - OAUTH_CLIENT_CREDENTIALS: The translation connector supports Client Credentials (two-Legged OAuth).
    
    To access Language Service Provider using Client Credentials in Identity Cloud Store (IDCS), (two-Legged OAuth), a token is requested for the client application and calls to the Language Service Provider APIs are made using this client application's token. The connector declares the custom fields required to obtain the token; for example, Client ID, Client Secret, and Scope. In addition, a custom field with fields ID accessToken must be declared. Every request made to the connector includes these custom fields in the request headers. In a new connector instance, the value of the accessToken field is empty. The connector should obtain an access token with the values of the other custom fields such as Client ID, Client Secret, and Scope. Once an access token is obtained, then the value should be set in the response header. The OCM connector framework saves the accessToken value in the response header. Subsequent requests for the connector will receive the accessToken.
    
    To revoke the access token generated in the two-legged OAuth flow, select Integrations from the left navigation panel, select Translation Connectors in the dropdown menu. Select the checkbox corresponding to the translation connector, click the Revoke Access Token button.
    
    Note:
    The Revoke Access Token button appears only when you’ve selected the checkbox corresponding to the connector, and the connector must be of type OAUTH_CLIENT_CREDENTIALS. Otherwise, the Revoke Access Token button will not appear.
  - NO_AUTH: The translation connector uses custom fields to specify fields such as Bearer token for authentication.
- Custom fields and properties: You can also use this interface to define custom fields for the translation connector. Custom properties are specific to a connector, so the connector framework can’t provide such a properties list by itself. Every translation connector has its own requirements to connect to a remote store; for example, one translation connector might need just Client ID and Client Secret, while another might require Client ID, Client Secret, App ID, and so on. Each translation connector can provide a custom properties list to the Oracle Content Management server by ServerResource. If any of these properties need to be filled in by an administrator during configuration, the connector framework can surface them in the Administration web interface and pass them through as header parameters on each request to the translation connector.
This service will be called only once, at the time of registration.
TranslationResource Interface: The connector framework uses this service to submit an Oracle Content Management translation job to the translation connector. The translation connector then calls the Language Service Provider to translate ,the zip file provided for the job and returns the translated zip.

Each of these interfaces is described in more detail, with examples of REST payloads, in the following sections:

REST Interfaces for Configuration and Authorization

A translation connector needs to implement the following REST APIs for defining the connector configuration and setting up authorization.

/rest/api
Implements intradoc.connectorcommon.server.APIResource
Here you return the latest version supported by the content connector.

GET http://host:port/connector/rest/api

[    "v1"]


/rest/api/v1/server
Implements intradoc.connectorcommon.server.ServerResource

This returns information about the translation connector configuration, like the authentication type and custom fields it exposes.

GET http://host:port/connector/rest/api/v1/server

{
    "name": "",
    "nameLocalizations": [{
        "locale": "en_US",
        "localizedString": "Sample Connector"
    }],
    "version": "(1,0,0)",
    "about": "This is a sample connector.Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.",
    "aboutLocalizations": [{
        "locale": "en_US",
        "localizedString": "This is a sample connector.Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved."
    }],
    "authenticationType": "NO_AUTH",
    "pickerType": "",
    "enableMultiUserCopyBack": false,
    "maxUploadSize": 1073741824,
    "fields": [{
        "ID": "ProxyHost",
        "datatype": "STRING",
        "siteSettable": true,
        "userSettable": false,
        "connectorSettable": false,
        "authorizationURLParameter": false,
        "label": "HTTP Proxy Hostname",
        "labelLocalizations": [{
            "locale": "en",
            "localizedString": "HTTP Proxy Hostname"
        }],
        "description": "The HTTP proxy hostname, leave blank to disable.",
        "descriptionLocalizations": [{
            "locale": "en",
            "localizedString": "The HTTP proxy hostname, leave blank to disable."
        }],
        "required": false
    }, {
        "ID": "ProxyPort",
        "datatype": "STRING",
        "siteSettable": true,
        "userSettable": false,
        "connectorSettable": false,
        "authorizationURLParameter": false,
        "label": "HTTP Proxy Port",
        "labelLocalizations": [{
            "locale": "en",
            "localizedString": "HTTP Proxy Port"
        }],
        "description": "The HTTP proxy port number, leave blank to default to port 80.",
        "descriptionLocalizations": [{
            "locale": "en",
            "localizedString": "The HTTP proxy port number, leave blank to default to port 80."
        }],
        "required": false
    }, {
        "ID": "ProxyScheme",
        "datatype": "STRING",
        "siteSettable": true,
        "userSettable": false,
        "connectorSettable": false,
        "authorizationURLParameter": false,
        "label": "HTTP Proxy Scheme",
        "labelLocalizations": [{
            "locale": "en",
            "localizedString": "HTTP Proxy Scheme"
        }],
        "description": "The HTTP proxy scheme, leave blank to default to http.",
        "descriptionLocalizations": [{
            "locale": "en",
            "localizedString": "The HTTP proxy scheme, leave blank to default to http."
        }],
        "required": false
    }, {
        "ID": "BearerToken",
        "datatype": "STRING",
        "siteSettable": true,
        "userSettable": false,
        "connectorSettable": false,
        "authorizationURLParameter": false,
        "label": "Bearer Token",
        "labelLocalizations": [{
            "locale": "en",
            "localizedString": "Bearer Token"
        }],
        "description": null,
        "descriptionLocalizations": [],
        "required": true
    }, {
        "ID": "WorkflowId",
        "datatype": "STRING",
        "siteSettable": true,
        "userSettable": false,
        "connectorSettable": false,
        "authorizationURLParameter": false,
        "label": "Workflow Id",
        "labelLocalizations": [{
            "locale": "en",
            "localizedString": "Bearer Token"
        }],
        "description": null,
        "descriptionLocalizations": [],
        "required": true
    }],
    "supportedConnectorTypes": [],
    "proprietorName": "",
    "serviceProviderName": "Sample APIs INC.",
    "nativeAppInfos": null
},


/rest/api/v1/authorization/authorizationURLs
Implements intradoc.connectorcommon.server.AuthorizationResource

This is required only if the custom translation UI is to be configured. It adds a new field "Translation Job Editor" in the fields of the custom translation connector in Oracle Content Management.

{
     "ID": "CustomTranslationUI_name",
     "datatype": "STRING",
     "siteSettable": true,
     "userSettable": false,
     "connectorSettable": false,
     "authorizationURLParameter": false,
     "label": "Custom Translation UI",
     "labelLocalizations": [{
             "locale": "en",
             "localizedString": "Custom Translation UI"
       }],
      "description": null,
      "descriptionLocalizations": [],
      "required": false
},
{
       "ID": "CustomTranslationUI_id",
       "datatype": "STRING",
       "siteSettable": true,
       "userSettable": false,
       "connectorSettable": false,
       "authorizationURLParameter": false,
       "label": "Translation Job Editor",
       "labelLocalizations": [{
             "locale": "en",
             "localizedString": "Custom Translation UI Id"
         }],
        "description": null,
        "descriptionLocalizations": [],
        "required": false
 },

The SDK exposes the following global object and properties that can be used in custom translation editor UI to find out the details about the translation job:

window.translationEditorSDK: {
  properties = {
      "connector": {
        "jobId": "string returned by the connector for the ID of the job",
        "title": "string for the name of the job"
      },
      "translationJob": {
        "type": ['assets' | 'sites']
        "data": "object providing additional information about the selected items based on job type"
      },
      "componentName": "string for the name of the translation editor component",
      "locale": "string for the locale of the page"
    }
}

This is required only if the translation connector supports OAUTH_CLIENT_CREDENTIALS. It adds custom fields to obtain an access token and the required accessToken field.


{
	"ID": "ClientID",
	"datatype": "STRING",
	"siteSettable": true,
	"userSettable": false,
	"connectorSettable": false,
	"authorizationURLParameter": false,
	"label": "ClientID",
	"labelLocalizations": [{
		"locale": "en",
		"localizedString": "ClientID"
	}],
	"description": null,
	"descriptionLocalizations": [],
	"required": true
},
{
	"ID": "ClientSecret",
	"datatype": "STRING",
	"siteSettable": true,
	"userSettable": false,
	"connectorSettable": false,
	"authorizationURLParameter": false,
	"label": "ClientSecret",
	"labelLocalizations": [{
		"locale": "en",
		"localizedString": "ClientSecret"
	}],
	"description": null,
	"descriptionLocalizations": [],
	"required": true
},
{
	"ID": "Scope",
	"datatype": "STRING",
	"siteSettable": true,
	"userSettable": false,
	"connectorSettable": false,
	"authorizationURLParameter": false,
	"label": "Scope",
	"labelLocalizations": [{
		"locale": "en",
		"localizedString": "Scope"
	}],
	"description": null,
	"descriptionLocalizations": [],
	"required": true
},
{
	"ID": "accessToken",
	"datatype": "STRING",
	"siteSettable": false,
	"userSettable": false,
	"connectorSettable": true,
	"authorizationURLParameter": false,
	"label": "null",
	"labelLocalizations": [{
		"locale": "en",
		"localizedString": null
	}],
	"description": null,
	"descriptionLocalizations": [],
	"required": false
}

This is required if the translation connector supports Additional Data fields.


"addtionalSettings": {
    "AdditionalDataFields": [
	{
	    "id": "business_division",
	    "name": "Business Division",
	    "type": "String"
	},
	{
	    "id": "email",
	    "name": "Email",
	    "type": "String"
	},
	{
	    "id": "purchase_order",
            "name": "Purchase Order",
	    "type": "String"
	},
	{
	    "id": "finish_by",
	    "name": "Finish By",
	    "type": "Date"
	}
    ]
}
"fields": [{
	 <<Other data>>
	{
	    "ID": "AdditionalData",
	    "datatype": "STRING",
	    "siteSettable": true,
	    "userSettable": false,
	    "connectorSettable": false,
	    "authorizationURLParameter": false,
	    "label": "Additional Data",
	    "labelLocalizations": [{
		"locale": "en",
	       "localizedString": "Additional Data"
	    }],
	    "description": null,
	    "descriptionLocalizations": [],
	    "required": true
        },
    }
    <<Other fields>>
]

REST Interfaces for Creating Translation Jobs and Returning Translated Content

A translation connector needs to implement he following REST APIs for creating translation jobs, providing status about the connector translation jobs, and returning the translation results for each job.

/rest/api/v1/job
Implements intradoc.connectorcommon.server.TranslationJobResource
Given an OCE Translation Job ID, create and return a connector project ID for the translation job.
POST http://host:port/connector/rest/api/v1/job

Request Headers
X-CEC-ClientID:client-id
X-CEC-ProxyHost:proxy-host
X-CEC-ProxyPort:80
X-CEC-ProxyScheme:http
X-CEC-TranslationJob:translation-job-name

Request Body
{Zipfilecontent}

Response Headers
content-type application/zip
content-length {zip file size}
  
Response Body
     {
            "properties": {
                "status": "IMPORTING",
                "id": "{{connectorJobId}}"
            }
        }

/rest/api/v1/job/{id}/translation
Implements intradoc.connectorcommon.server.TranslationJobResource
Given a connector job id, return the translated zip file. 
GET http://host:port/connector/rest/api/v1/job/{id}/translation

Request Headers
X-CEC-ClientID:client-id
X-CEC-ProxyHost:proxy-host
X-CEC-ProxyPort:80
X-CEC-ProxyScheme:http
X-CEC-TranslationConnectorJobId:connector-job-id

Request Body

   
Response Headers
content-type application/zip
content-size {zip file size}
  
Response Body
     {streamed zip file}



/rest/api/v1/job/{id}
Implements intradoc.connectorcommon.server.TranslationJobResource
Given a connector job id, delete the connector job from the connector. 
DELETE http://host:port/connector/rest/api/v1/job/{id}

Request Headers
X-CEC-ClientID:client-id
X-CEC-ProxyHost:proxy-host
X-CEC-ProxyPort:80
X-CEC-ProxyScheme:http
X-CEC-TranslationConnectorJobId:connector-job-id

Request Body

   
Response Headers
content-type application/json
  
Response Body
     {Message noting successful deletion}