Create project groups from scratch

Create as many project groups as you need in one call.

For security reasons, you need to perform a Login action before making any other public calls to the WorldServer API. The sessionId in the response is your session token. Use this token in all the other calls that you make.

Also, make sure that you have the appropriate user type permissions to perform this API call. To view or update your permissions, in WorldServer, go to Management > User Setup > User Types, and then select your user type.

Prerequisites

To create a project group from scratch, you need the following:
  • The ID of the project type that you will use for your new project group.
  • The ID of the client that you will use for your new project group.
  • The internalName of each asset that you want to translate as part of the project group.
  • The IDs of the locales that you will use for your new project group.
You can obtain these details by making the calls mentioned as related links at the end of this topic.

API call

<protocol>://<ws-host>:<ws-port>/ws-api/v2/projectGroups/create?token=<sessionId>

Details

  • POST method
  • The internalName generated when uploading the file is required in the body of the request.
  • Content-Type in the header: application/json
  • Mandatory parameters:
    • the session token (as a query string parameter or as a key-value pair in the header)
    • a JSON body with the following mandatory details: name (the name of the project group that you want to create), projectTypeId (the ID of the project type on which the newly created project group will be based), clientId (the ID of the client that you will use for the project group), systemFiles (the assets of the project group), locales (the IDs of the locales that you will use for the project group)
  • Optional parameter: expandZip—If you set it to true and you uploaded a .zip file, WorldServer automatically extracts the assets included in the .zip file.

JSON body examples

A single project group created, with three locales (projects) and one task each:A possible JSON body that shows how to create a project group with three locales (projects) and one task each.
Several project groups created, with 21 locales (projects) and three tasks each:A possible JSON body that shows how to create multiple project groups with 21 locales (projects) and three tasks each.

Creating tasks only for specific locales

Starting with WorldServer 11.8.2, the Create Project Group endpoint was extended with an additional and optional setting (localisedFiles) that you can use to map assets to locales. Instead of automatically creating a task in all project locales for a particular uploaded asset, you can now configure WorldServer to create tasks only in the project locales mapped to that asset.

For example, your project group has three target locales (English – "id": 1001, French – "id": 1002, and German – "id": 1003) and three uploaded assets (test1.docx, test2.docx, and test3.docx). You configure the localisedFiles model as follows:
  • test1.docx is mapped to English and French.
  • test2.docx is mapped to French and German.
  • test3.docx is mapped to all three target locales.
A screen shot of the mapping in an API request body.The resulting project group will contain three projects (one for each target locale) with the following characteristics:
  • The English project will have two tasks – one for test1.docx and one for test3.docx
  • The French project will have three tasks, corresponding to all three assets.
  • The German project will have two tasks – one for test2.docx and one for test3.docx
If the localisedFiles request model is not present in the body, the request will create tasks for all the locales.
A screenshot of the configuration integrated in a larger API request body.

Response

A screen shot that shows a typical response to this call.

Error messages

MessageStatus code
Invalid JSON400 Bad Request
Could not process the given file (Make sure the file was already uploaded as an asset.)400 Bad Request
Field name not set400 Bad Request
Field projectTypeId not set400 Bad Request
Field Id is null (The client ID is mandatory.)400 Bad Request
Resource LOCALE (ID) not found400 Bad Request
The provided due date selected for the projects is in the past400 Bad Request
Locales should be presented with a non-empty value400 Bad Request
Project type is not assigned to the client400 Bad Request
User is not a member of the client (Make sure that the user belongs to the specified client.)400 Bad Request
No session token provided or invalid token401 Unauthorized
Resource CLIENT (ID) not found404 Not Found
Resource PROJECT_TYPE (ID) not found404 Not Found

Troubleshooting

  • Make sure that the endpoint you are calling is correct.
  • Make sure that you are using the POST method for the call.
  • Make sure that the Content-Type in the header is application/json.
  • Make sure that your session token is correct and that it has not expired.
  • Project group creation depends on project types, clients, and users. Make sure that the information you specify is valid (for example, the project type should be assigned to the client and the user should be a member of the client).