Skip to main content

SOAP API

Project creation

In the SOAP API, you can use these project creation-related methods:

Methods 3 and 4 are only available to in-house Project Managers. They include all the settings available in methods in 1 and 2, but also permit additional settings described at the end of this section.

  1. createProjectURL()

    Based on the file URL, it requires XTMProjectURLAPI object.

  2. createProjectMTOM()

    Based on the MTOM objects, it requires XTMProjectMTOMAPI object.

  3. createProjectForPMURL()

    Creates a project with additional settings only available to in-house Project Managers. Based on file URL, requires XTMProjectForPMURLAPI.

  4. createProjectForPMMTOM()

    Creates a project with additional settings only available to in-house Project Managers. Based on MTOM or BASE64 depending on the chosen web service, requires XTMProjectForPMMTOMAPI.

XTMProjectBaseAPI – the base project information:

Table 10. : XTMProjectBaseAPI – the base project information

Option

Description

String name

Name of the project. (Optional – if not present, will be auto-generated.)

LANGUAGE_CODE sourceLanguage

Source language. (Mandatory)

List<LANGUAGE_CODE> targetLanguages

Target languages. (Mandatory, at least one must be present.)

XTMCustomerDescriptorAPI customer

Customer descriptor.

Date dueDate

Due date. (Optional, if missing, the current date is assumed.)

XTMDomainDescriptorAPI domain

Domain descriptor.

XTMWorkflowDescriptorAPI workflow

Workflow descriptor. (Mandatory)

XTMWorkflowDescriptorAPI workflowForNonAnalyzableFiles

Workflow descriptor for non-analyzable files. (Optional)

XTMExternalProjectDescriptorAPI externalDescriptor

External project descriptor. (Optional)

XTMTemplateDescriptorAPI template

Templates can be used to create a project. If any project field is not specified in this object,then if it is available it will be taken from the template. (Optional.)

XTMAnalysisTemplateDescriptorAPI analysisTemplate

Analysis template descriptor. (Optional)


XTMProjectAPI extends XTMProjectBaseAPI – the extended project information:

Table 11. : XTMProjectAPI extends XTMProjectBaseAPI – the extended project information

Option

Description

String description

Additional description. (Optional)

String referenceId

The reference ID. (Optional)

Boolean useGoogleMachineTranslation

Information on whether the Linguists should have the possibility to use Google machine translation help. (Optional)

Boolean usesNotApprovedTranslationMemory

Information on whether non-approved translation memory should be used. (Optional)

Boolean allowEditingOfICEMatches

Allows editing ICE matches. (Optional)

WorkflowStepUsageEnum nonTransAsDONE

Specifies in which steps non-translatables should be marked as completed. (Optional)

WorkflowStepUsageEnum leveragesAsDONE

Specifies in which steps leverages should be marked as completed. (Optional)

WorkflowStepUsageEnum notApprovedLeveragesAsDONE

Specifies in which steps matches from non-approved TM should be marked as completed. (Optional)

WorkflowStepUsageEnum notApprovedExactMatchesAsDONE

Specifies in which steps exact matches from non-approved TM should be marked as completed. (Optional)

XTMUserBaseDescriptorAPI projectManager

Possibility to assign a specified Project Manager (optional). Cannot be used with pre-processing (newSourceLanguage).

XTM_FILE_PROCESS fileProcessType

Possibility to join files (optional). Cannot be used with pre-processing (newSourceLanguage).

XTMPenaltyProfileDescriptorAPI tmPenaltyProfile

Possibility to set TM penalty profile.

List<XTMTagDescriptorAPI>tmTags

Possibility to define a list of TM tags.

XTMPenaltyProfileDescriptorAPI termPenaltyProfile

Possibility to set a term penalty profile.

List<XTMTagDescriptorAPI>termTags

Possibility to define a list of term tags.

XTMProjectManagerTypeEnum projectManagerType

Specifies a Project Manager who manages the customer.

XTMProjectCallbackAPI projectCallback

Possibility to assign links that should be called on specific project actions.

XTMMatchingAPI matchingOptions

Matching options.

LANGUAGE_CODE newSourceLanguage

New source language code (pivot language code). Cannot be used with the join files option. (fileProcessType - JOIN)

XTMWorkflowDescriptorAPI newSourceWorkflow

New source workflow descriptor.

XTMTermAllowNotApproveEnum allowNotApproveTerm

Possibility to use non-approved terms in the decoration process.

Boolean useTerminologyDecoration

Possibility to disable terminology decoration (by default, this is enabled).

XTMAutoWorkflowFinishEnum autoWorkflowFinish

Possibility to automatically finish steps where all segments are completed.

List<XTMCustomFieldAPI> projectCustomFields

Possibility to set project custom fields.


XTMProjectURLAPI extends XTMProjectAPI:

Table 12. : XTMProjectURLAPI extends XTMProjectAPI

Option

Description

List<XTMFileURLAPI> translationFiles

Files requiring translation (Optional – If not set, then a project without files for translation will be created.)

List<XTMFIleURLAPI> materialFiles

Reference Material files. (Optional)


XTMProjectMTOMAPI extends XTMProjectAPI:

Table 13. : XTMProjectMTOMAPI extends XTMProjectAPI

Option

Description

List<XTMFileMTOMAPI> translationFiles

Files requiring translation. (Optional – If not set, then a project without files for translation will be created.)

List<XTMFileMTOMAPI> materialFiles

Reference Material files. (Optional)


XTMFileURLAPI and XTMFileMTOMAPI extend XTMFileAPI , which contains:

Table 14. : XTMFileURLAPI and XTMFileMTOMAPI extend XTMFileAPI, which contains:

Option

Description

String filename

File name.

Map<LANGUAGE_CODE, XTMExternalJobDescriptorAPI> externalDescriptors

External job descriptors. It maps the external ID to the combination of the source file and language code.

List<LANGUAGE_CODE> targetLanguages

List of target languages for this file. If not specified, the target languages for the project will be used.


Example 1.

File for translation: simple.txt.

Target languages: pl_PL, ru_RU.

In this case, 2 jobs will be created in XTM Cloud. External descriptors create the possibility to assign an external ID for each job (file with a language pair).


XTMExternalProjectDescriptorAPI: integrationId

The external project descriptor needs to be specified to use the project integration ID in other methods instead of the project ID from XTM Cloud.

XTMExternalJobDescriptorAPI: integrationId

The external job descriptor needs to be specified to use the job integration ID in other methods instead of the job ID from XTM Cloud.

XTMProjectCallbackAPI: projectFinishedCallback, jobFinishedCallback, analysisFinishedCallback, and workflowTransitionCallback

Includes URLs that should be called on specific project actions:

  • projectFinishedCallback

    This link is called when the project is finished. Additionally, the xtmProjectId and xtmCustomerId parameters are added to the URL.

  • jobFinishedCallback

    This link is called when the job is finished. Additionally, the xtmProjectId, xtmJobId, and xtmCustomerId parameters are added to the URL.

  • analysisFinishedCallback

    This link is called when the project analysis has finished. The callback includes information about the project and jobs sent in JSON format. Additionally, the xtmProjectId and xtmCustomerId parameters are added to the URL.

  • workflowTransitionCallback

    This link is called when the workflow event has occurred. Each event in the workflow will generate a notification with all the details about the tasks in a JSON format. Additionally, the xtmProjectId and xtmCustomerId parameters are added to the URL.

    • Possible workflow tasks:

      • ACTIVE – task has been activated.

      • FINISHED – task has been finished.

      • DEACTIVATED – task has been deactivated.

      • REASSIGNED – task has been reassigned to a different user.

      • OPENED – task has been reopened.

      • OPENED_BUT_WAITING – task is reopened but currently inactive while waiting for other bundles.

      • REMOVED – task has been removed.

      • DUE_DATE_CHANGED – due date in the task has been changed.

    • Workflow task includes information about:

      • file.

      • step.

      • bundle.

      • target language.

XTMMatchingAPI: fuzzySearch, fuzzyC1Visibility, fuzzyC2Visibility, fuzzyC3Visibility

  • fuzzySearch

    Specifies when to search for fuzzy matches.

    (XTMMatchingFuzzySearchEnum)

  • fuzzyC1Visibility, fuzzyC2Visibility, fuzzyC3Visibility

    Specifies when fuzzy matches are visible.

    (XTMMatchingFuzzyVisibilityEnum)

fuzzyC1Visibility = 95 – 99%

fuzzyC2Visibility = 85 – 94%

fuzzyC3Visibility = 75 – 84%

Each creation method returns an XTMProjectResponseAPI object, which includes:

  • project descriptor.

  • name.

  • jobs – a list of XTMJobResponseAPI objects which contain:

    • job descriptor.

    • file name.

    • source language.

    • target language.

XTM_WORKFLOWS – possible general workflows in XTM Cloud:

Table 15. : XTM_WORKFLOWS – possible general workflows in XTM Cloud

Option

Description

TRANSLATE

Define for 'translate'.

TRANSLATE_F_REVIEW

Define for 'translate hashtag-solid.svg review'.

In the New Workflow Editor: 'translate two_straight_lines.svg review'

TRANSLATE_F_REVIEW_F_REVIEW

Define for 'translate hashtag-solid.svg review hashtag-solid.svg review'.

In the New Workflow Editor: 'translate two_straight_lines.svg review two_straight_lines.svg review'

TRANSLATE_P_CORRECT

Define for 'translate arrow-right-solid.png correct'.

In the New Workflow Editor: 'translate two_lines_one_dashed.svg correct'

TRANSLATE_P_CORRECT_P_CORRECT

Define for 'translate arrow-right-solid.png correct arrow-right-solid.png correct'.

In the New Workflow Editor: 'translate two_lines_one_dashed.svg correct two_lines_one_dashed.svg correct'

TRANSLATE_CORRECT

Define for 'translate comma.svg correct'.

In the New Workflow Editor: 'translate dashed_vertical_line.svg correct'

TRANSLATE_REVIEW

Define for 'translate comma.svg review'.

In the New Workflow Editor: 'translate dashed_vertical_line.svg review'

TRANSLATE_REVIEW_P_REVIEW

Define for 'translate comma.svg review arrow-right-solid.png review'.

In the New Workflow Editor: 'translate dashed_vertical_line.svg review two_lines_one_dashed.svg review'

TRANSLATE_CORRECT_P_REVIEW

Define for 'translate comma.svg correct arrow-right-solid.png review'.

In the New Workflow Editor: 'translate dashed_vertical_line.svg correct two_lines_one_dashed.svg review'

TRANSLATE_F_CORRECT

Define for 'translate hashtag-solid.svg correct'.

In the New Workflow Editor: 'translate two_straight_lines.svg correct'

TRANSLATE_P_CORRECT_F_REVIEW

Define for 'translate arrow-right-solid.png correct hashtag-solid.svg review'.

In the New Workflow Editor: 'translate two_lines_one_dashed.svg review two_straight_lines.svg review'

TRANSLATE_F_CORRECT_F_REVIEW

Define for 'translate hashtag-solid.svg correct hashtag-solid.svg review'.

In the New Workflow Editor: 'translate two_straight_lines.svg correct two_straight_lines.svg review'


WorkflowStepUsageEnum – possible steps where leverages and non-translatables can be marked as completed

Table 16. : WorkflowStepUsageEnum – possible steps where leverages and non-translatables can be marked as completed

Option

Description

NONE

None.

ALL_STEPS

In all steps.

FIRST_STEP

Only in the first step.

NOT_LAST_STEP

All steps except the last.


XTM_FILE_PROCESS – possible ways of file processing:

Table 17. : XTM_FILE_PROCESS – possible ways of file processing

Option

Description

JOIN

Join files.


XTMProjectManagerTypeEnum – possible ways of Project Manager assignment:

Table 18. : XTMProjectManagerTypeEnum – possible ways of Project Manager assignment

Option

Description

FROM_CUSTOMER

From customer.


XTMMatchingFuzzySearchEnum – criteria for searching fuzzy matches:

Table 19. : XTMMatchingFuzzySearchEnum – criteria for searching fuzzy matches

Option

Description

ALWAYS

Always search for fuzzy matches.

EVEN_ICE_FOUND

Search for fuzzy matches even if an ICE match is found.

EVEN_LEVERAGED_FOUND

Search for fuzzy matches even if 100% matches are found.

NEVER

Never search for fuzzy matches.


XTMMatchingFuzzyVisibilityEnum – options for fuzzy match visibility:

Table 20. : XTMMatchingFuzzyVisibilityEnum – options for fuzzy match visibility

Option

Description

YES

Always show fuzzy matches.

ONLY_IF_ITS_APPROVAL_STATUS_IS_HIGHER_THAN_THE_ICE_OR_LEVERAGED_MATCH

Only if its approval status is higher than the ICE or leveraged match.

ONLY_IF_ITS_XLIFFDOC_STATUS_IS_HIGHER_THAN_THE_ICE_OR_LEVERAGED_MATCH

Only if its XLIFF:doc status is higher than the ICE or leveraged match.

ONLY_IF_ITS_APPROVAL_AND_XLIFFDOC_STATUS_ARE_HIGHER_THAN_THE_ICE_OR_LEVERAGED_MATCH

Only if its approval and XLIFF:doc status are higher than the ICE or leveraged match.

NO

Do not show fuzzy matches.


XTMTermAllowNotApproveEnum – options for using not approved terms in decoration process:

Table 21. : XTMTermAllowNotApproveEnum – options for using not approved terms in decoration process

Option

Description

ALLOW

Not approved terms will be used.

DISALLOW

Not approved terms will not be used.


Forbidden characters in the project name

A project name cannot contain any of the following characters: \, /, :, *, ?, “, <, >, |

Special characters in the file URL

If a translation file URL contains one of the specific characters below, then an additional URL transformation is required to make the file available for the Web Service. The table below shows how specific characters should be processed.

Table 22. : Special characters in the file URL

Character

Encoded character

URL example

%20

http://test%20.xml

`

%60

http://test%60.xml

~

~

http://test~.xml

!

!

http://test!.xml

@

@

http://test@.xml

#

%23

http://test%23.xml

$

$

http://test$.xml

%

%25

http://test%25.xml

^

%5E

http://test%5E.xml

&

%26

http://test%26.xml

(

(

http://test(.xml

)

)

http://test).xml

-

-

http://test-.xml

_

_

http://test_.xml

=

=

http://test=.xml

+

+

http://test+.xml

{

%7B

http://test%7B.xml

}

%7D

http://test%7D.xml

[

%5B

http://test%5B.xml

]

%5D

http://test%5D.xml

;

;

http://test;.xml

‘

‘

http://test’.xml

,

,

http://test,.xml

.

.

http://test..xml

*

Forbidden

:

Forbidden

“

Forbidden

<

Forbidden

>

Forbidden

?

Forbidden

/

Forbidden

|

Forbidden

\

Forbidden


Additional settings for methods 3 and 4:

  • A list of TM Customers (XTMCustomerDescriptorAPI objects).

    This provides the possibility to specify that the project should use the TM of multiple customers. This option requires customer descriptors.