Example - using the API to clone a project and replace the files

The Rigi API provides functionalities to create a project based on another project. This may be handy if you need to create Rigi projects on a regular basis, that all have more or less the same settings as an existing project. The only difference is the files that are specified in the workspace. This article demonstrates how to use the API in that case.

The API documentation is available on <yourserver>.rigi.io.

This description may be useful if you want to build a Rigi connector for

1. e-commerce systems (ECS), or
   
2. product information management systems (PIM), or
   
3. content management systems (CMS).
   

This article describes the scenario to clone the project from a project named TEMPLATE, give it a PROJECT_NAME, upload a new set of source files, and approve the workspace and string list.

1. Make sure that no project with the name PROJECT_NAME already exists.
2. Clone a project. This clones a complete project, including files, parser settings, users, etc.
3. Upload the new set of files to the workspace.
4. Approve the workspace
5. Sync the string list.

Each step is described in the following sections.

API: Project name exists

GET /api/projects/names?name=PROJECT_NAME

This returns an object with Boolean exists.

API: Clone

After you initiated the clone of a project, you need to wait until the completion.

Keep it small!

1. If the source project is a template, ensure that the size is as limited as possible.
   
2. To copy parser settings, the source project needs to have at least one file with the required parser settings,
   Use a small file in the source project with for example only one source string.

Initiate the clone

POST /api/projects/clone?full-true

This will initiate a full clone of the project.

Wait until the clone is ready

The actions-endpoint provides insight in the status of a project.

GET api/projects/actions?name=PROJECT_NAME

It returns the an object with the project id, project name and status details regarding operations.

1. {
2. "projectId": "12345",
3. "name": "PROJECT_NAME",
4. "details": {
5. "projectCloneStatus": "1",
6. "workspaceFilesStatus": "1",
7. "workspaceApproveStatus": "1",
8. "workspaceMergeStatus": "1"
9.        }
10. }

The status values can be:

1. "0" : the operation is still in-progress.
   
2. "1" : the operation is ready.
   
3. "2" : there is an error.

Cloning a smaller project may take 10 seconds or so. Poll the projectCloneStatus each second and wait until the operation is ready.

1. while (true)
2. {
   
3.      wait 1 second
   
4.      get project status   
5.      if (projectCloneStatus == "1")
6.             return READY
7.      else if (projectCloneStatus == "2")
8.             return ERROR
9. }

API: Upload the new set of files to the workspace

Pseudo code:

1. Create the manifest file based on files to be uploaded
   
2. Create the ZIP to be uploaded with manifest and files
3. //workspaceFilesStatus == ready ("1")
   
4. Prepare upload. Set workspaceFilesStatus to in-progress ("0")
   
5. Upload the ZIP
   
6. //Server waits for the ZIP, and updates the workspace.
7. Wait until upload completed (e.g. workspaceFilesStatus == ready ("1"))

Create manifest file

The manifest file (manifest.json) is located in the root of the ZIP file that will be uploaded. The manifest contains the following fields:

Field	Required	Description
filepath	Required	Relative file path in the ZIP file. Examle: abc\def\myfile.json
parserId	Required	Parser id. You can find it in the parser settings of your source project. Example: json.
targetRule	Optional	Name of the target rule that shall be applied for this file. If no target rule is specified, the rule will be used that is assigned to the first file with this extension in the template project.
fileId	Optional	File identifier that will assigned to this file. If no file id is specified, and the template project contains a file with the same name, then that id is used. If no file id is specified, and the template project does not contain a file with the same name, then the system will auto-create a file-id.

Create the zip

Create the zip file that contains the manifest and the files. For example:

In this example, the manifest file is:

1. [
   
2.   {  "filepath": "en-CA.json",  "parserId": "json",  "targetRule": null,  "fileId": null },
   
3.   {  "filepath": "hello.json",    "parserId": "json",  "targetRule": null,  "fileId": null },
4.   {  "filepath": "nl-NL.json",   "parserId": "json",  "targetRule": null,  "fileId": null }
5. ]
   

Prepare the upload

POST /api/projects/{id}/actions
Body: { "workspaceFilesStatus" : "0" }

Similar like we had to wait until cloning the workspace was completed, we also must wait until all files are processed. There is some time between uploading the ZIP and when the server starts processing that file. To be able to detect when the server has processed the ZIP, we need to mark the workspaceFilesStatus as in-progress ("0") ourselves.

Upload

POST api/projects/{id}/workspaces/files

This operation uploads the ZIP to the workspace. The Rigi server will add the files that are defined in the workspace to the project.

Wait until upload completed

The upload operation may take a while.

1. while (true)
2. {
   
3.      wait 1 second
   
4.      get project status   
5.      if (workspaceFilesStatus == "1")
6.             return READY
7.      else if (workspaceFilesStatus == "2")
8.             return ERROR
9. }

Approve the workspace

Pseudo code:

1. Approve the workspace
   
2. Wait until approval completed (e.g. workspaceApproveStatus== ready ("1"))

API: Approve the workspace

POST api/projects/{id}/workspaces/files/approve

Wait until approved

1. while (true)
2. {
   
3.      wait 1 second
   
4.      get project status   
5.      if (workspaceApproveStatus== "1")
6.             return READY
7.      else if (workspaceFilesStatus == "2")
8.             return ERROR
9. }

API: Sync the string list

This will update the string list with the files that were uploaded and assigned to the project.

1. Sync the string list
   
2. Wait until sync completed (e.g. workspaceMergeStatus== ready ("1"))

Sync

PUT api/projects/{id}/workspaces/merge

Wait until synced

1. while (true)
2. {
   
3.      wait 1 second
   
4.      get project status   
5.      if (workspaceMergeStatus== "1")
6.             return READY
7.      else if (workspaceMergeStatus== "2")
8.             return ERROR
9. }

• Related Articles

• API endpoints with sockets

  API calls exceeding one minute will result in a timeout. To address this, we have introduced a socket connection mechanism. Here's the refined explanation of the process: Client Initiation: To begin, the client initiates a room specifically ...

• File formats

  Rigi supports most file formats for software texts, including: Angular XLF CMS Typo3 Wordpress Excel and CSV Excel and CSV Parser - One file per target language (mono) Excel and CSV Parser - One file with all languages (multi) Flutter arb-files. ...

• Asim XML

  ​​​​The Asim Product Information Management (PIM) system can export XML files for translation and import the translated files. Rigi has tooling to capture live links. When a translator selects a text, it will open the URL with the correct page in the ...

• Capture HTML Previews for iOS mobile apps

  This article explains the steps how to prepare the iOS development environment and capture HTML Previews for mobile iOS applications. Intended audience - Developers Steps to capture HTML Previews Rigi SDK for iOS Developers need to install the a Rigi ...