Edit

Asset Bundle migration API

tip

• To explore Asset Bundle migration via the Control Tower user interface, refer to Import Asset Bundle via Control Tower UI.
• To make API requests on a Windows 10 machine shipped with cURL, refer to the Windows 10 cURL example section.

Authentication

Asset Bundle migration API uses form-based (login and password) authentication to ensure that it is only accessible to users with proper credentials.

Note that CSRF protection is added to REST endpoints. To make a REST call, add a CSRF token to the request header:

1. Before executing REST API requests, log in using the form URL:

   POST method

   POST /workfusion/api/dologin
   Content-Type: application/x-www-form-urlencoded
   j_username=usernamej_password=password
   

   where:

   • j_username is your username in Control Tower.
   • j_password is your password in Control Tower.

2. The body of a successful request from the server looks like this:

   {
       "success": true,
       "csrfToken": <csrftoken>,
       "csrfHeaderName": <csrftokenname>
   }
   

3. Get JSESSIONID from the Set-Cookie response header.

4. When creating REST API requests:

   1. Set JSESSIONID to the Cookie header.
   2. Set application/x-www-form-urlencoded as the Content-Type header.
   3. Set the received <csrftoken> as the <csrftokenname> header.

For more information on the API security, see WorkFusion REST API documentation.

Using REST API with SSO

Starting from IA Cloud v.10.2, you can authenticate REST requests with your Keycloak credentials without making Control Tower changes.

Note that you must have the password assigned to your user. This condition is mandatory because, when using SSO, a user appears in Keycloak only after their first login via the interface, while Keycloak won't accept the user's password.

For more information, read the Configure Identity Providers and REST API authentication with enabled IDP topics.

Using REST API with LDAP

Starting from IA Cloud v.10.2, LDAP access is configured via Keycloak. So, you can authenticate REST requests with your Keycloak credentials. For more information, read the Configure LDAP topic.

Import

Import strategies

For importing Asset Bundles, you can choose one of the following strategies:

• REPLACE

  It is the default import strategy. If a file from a bundle is found on a target environment by a key attribute (for example, name), the file is overwritten. Instead, the target environment uses the imported one.

• SKIP_DATASTORES

  The strategy facilitates use case development, enabling one to avoid data losses due to multiple asset replacements. It behaves similarly to the REPLACE strategy for all files in an Asset Bundle, but for Data Stores and Training sets.

  According to the SKIP_DATASTORES strategy, if a Data Store or a Training Set from an Asset Bundle is found on a target environment by a key attribute (for example, name), the file is skipped during import. The target environment continues to use already existing files. Other files in the same Asset Bundle are imported in accordance with the REPLACE strategy.

To apply one of the two strategies, set the conflictResolutionStrategy parameter for POST/ bundle-import.

POST /bundle-import

Uploads an Asset Bundle to a temporary folder, validates the bundle structure, and starts asynchronous import.

Returns the import UUID and status. The following statuses are possible:

• ACCEPTED: successful import start
• UPLOAD_FAILED: failed bundle upload to the temporary folder
• VALIDATION_FAILED: incorrect checksum or bundle structure
• FAILED: occurred errors

Parameters

• bundleFile: Path to the zip file representing the Asset Bundle. The acceptable size is up to 3 GB.
• conflictResolutionStrategy: Optional; set to SKIP_DATASTORES or REPLACE, depending on whether you want to apply the SKIP_DATASTORES or REPLACE import strategy, accordingly. The values are non-case-sensitive. When you specify no value for the parameter, the import operation uses the default REPLACE strategy.
• checksum: Optional; md5 checksum of the Asset Bundle. type=text/plain is mandatory; otherwise, the checksum is ignored.

Request example

curl --request POST \
--url https://demoserver.com/workfusion/api/v1/bundle-import/
--header 'X-CSRF-TOKEN: 87345da0-9ccb-475e-bdb6-f323f6d0a2d3 \
--header 'cache-control: no-cache' \
--header 'content-type: multipart/form-data' \
--form 'bundleFile=@/C:/V2_bundle.zip' \
--form 'conflictResolutionStrategy=SKIP_DATASTORES' \
--form checksum=8401f840cd7ab27d0829a47120dae341;type=text/plain

Successful response example

{
    "uuid": "a91bc45a7-8acb-4466-bdb6-f434f6d1b3e4",
    "bundleName": "FIS_V2_BUNDLE",
    "importStatus": "ACCEPTED",
    "errors": [],
    "warnings": []
}

Failed response example

{
    "uuid": null,
    "bundleName": "FIS_V2_BUNDLE",
    "importStatus": "VALIDATION_FAILED",
    "errors": [
        "Checksum not identical"
    ],
    "warnings": []
}

GET /bundle-import/{uuid}

Checks the status of the import operation and returns the bundle import information, including:

• Status of the entire bundle
• Status of each component in a bundle, for instance, a Data Store, a Business Process, and so on
• Statistics fields, for example, the count of in-progress assets, the number of failed assets, and so on
• Messages generated during import

Possible statuses for entire bundle import:

• RUNNING

  Import in progress. Some components could be already imported with a SUCCEED or FAILED status.

• SUCCEED

  Import of all components completed successfully.

• FAILED

  Asset bundle import completed with errors. Check error messages for failed components.

Possible statuses for component import:

• RUNNING

  Import in progress.

• SUCCEED

  Import completed successfully.

• FAILED

  Import completed with errors. Check the error messages for the component.

Request example

curl --request GET \
  --url https://host/workfusion/api/v1/bundle-import/c5926adb-b669-46dc \
  --header 'X-CSRF-TOKEN: 87345da0-9ccb-475e-bdb6-f323f6d0a2d3' \
  --header 'cache-control: no-cache'

Response example

{
    "status": "SUCCEEDED",
    "inProgressCount": 0,
    "importedCount": 5,
    "failedToImportCount": 0,
    "skippedCount": 0,
    "infos": [
        "[business-process/KYC+remediation_+negative+news+v10.1.zip]: Submit asset for process",
        "[business-process/KYC+remediation_+negative+news+v10.1.zip]: Start handle asset by path",
        "[business-process/KYC+remediation_+negative+news+v10.1.zip]: Business process successfully imported, full import log: https://core2-workfusion-lb1.workfusion.com:443/workfusion/secure/file/download?uuid=1ff9562e-fad8-45e1-9f46-1763f516127d",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/google-translate-bcb/10.1/google-translate-bcb-10.1.jar]: Submit asset for process",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/google-translate-bcb/10.1/google-translate-bcb-10.1.jar]: Start handle asset by path",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/google-translate-bcb/10.1/google-translate-bcb-10.1.jar]: Asset successfully submitted",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-input-bcb/10.1/negativenews-input-bcb-10.1.jar]: Submit asset for process",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-input-bcb/10.1/negativenews-input-bcb-10.1.jar]: Start handle asset by path",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-input-bcb/10.1/negativenews-input-bcb-10.1.jar]: Asset successfully submitted",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-output-bcb/10.1/negativenews-output-bcb-10.1.jar]: Submit asset for process",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-output-bcb/10.1/negativenews-output-bcb-10.1.jar]: Start handle asset by path",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-output-bcb/10.1/negativenews-output-bcb-10.1.jar]: Asset successfully submitted",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-processing-bcb/10.1/negativenews-processing-bcb-10.1.jar]: Submit asset for process",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-processing-bcb/10.1/negativenews-processing-bcb-10.1.jar]: Start handle asset by path",
        "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-processing-bcb/10.1/negativenews-processing-bcb-10.1.jar]: Asset successfully submitted"
    ],
    "warnings": [],
    "errors": [],
    "name": "artifactory-dependency",
    "validationErrorMessage": null,
    "metaInfo": {
        "author": "dgorodetski",
        "description": "",
        "instance": "rcm-3162-v2-workfusion-lb1.workfusion.com",
        "name": "KYC remediation: negative news v10.1",
        "packageDate": 1570083971000,
        "targetVersion": "10.0.0; 10.1.0.0",
        "wfBranch": "master",
        "wfRevision": "9a351d4c",
        "wfVersion": "10.1.0.0",
        "unknownProperties": {}
    },
    "components": [
        {
            "status": "SUCCEEDED",
            "inProgressCount": 0,
            "importedCount": 1,
            "failedToImportCount": 0,
            "skippedCount": 0,
            "infos": [
                "[business-process/KYC+remediation_+negative+news+v10.1.zip]: Submit asset for process",
                "[business-process/KYC+remediation_+negative+news+v10.1.zip]: Start handle asset by path",
                "[business-process/KYC+remediation_+negative+news+v10.1.zip]: Business process successfully imported, full import log: https://core2-workfusion-lb1.workfusion.com:443/workfusion/secure/file/download?uuid=1ff9562e-fad8-45e1-9f46-1763f516127d"
            ],
            "warnings": [],
            "errors": [],
            "componentName": "BUSINESS_PROCESS",
            "importDetails": {
                "business-process/KYC+remediation_+negative+news+v10.1.zip": {
                    "uuid": "de30aba3-0c8d-44a8-b6ef-bdef5830a0ef"
                }
            }
        },
        {
            "status": "SUCCEEDED",
            "inProgressCount": 0,
            "importedCount": 4,
            "failedToImportCount": 0,
            "skippedCount": 0,
            "infos": [
                "[artifactory-dependency/bcb/com/workfusion/gorilla/google-translate-bcb/10.1/google-translate-bcb-10.1.jar]: Submit asset for process",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/google-translate-bcb/10.1/google-translate-bcb-10.1.jar]: Start handle asset by path",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/google-translate-bcb/10.1/google-translate-bcb-10.1.jar]: Asset successfully submitted",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-input-bcb/10.1/negativenews-input-bcb-10.1.jar]: Submit asset for process",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-input-bcb/10.1/negativenews-input-bcb-10.1.jar]: Start handle asset by path",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-input-bcb/10.1/negativenews-input-bcb-10.1.jar]: Asset successfully submitted",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-output-bcb/10.1/negativenews-output-bcb-10.1.jar]: Submit asset for process",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-output-bcb/10.1/negativenews-output-bcb-10.1.jar]: Start handle asset by path",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-output-bcb/10.1/negativenews-output-bcb-10.1.jar]: Asset successfully submitted",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-processing-bcb/10.1/negativenews-processing-bcb-10.1.jar]: Submit asset for process",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-processing-bcb/10.1/negativenews-processing-bcb-10.1.jar]: Start handle asset by path",
                "[artifactory-dependency/bcb/com/workfusion/gorilla/negativenews-processing-bcb/10.1/negativenews-processing-bcb-10.1.jar]: Asset successfully submitted"
            ],
            "warnings": [],
            "errors": [],
            "componentName": "ARTIFACTORY_DEPENDENCY",
            "importDetails": {}
        }
    ]
}

Export

POST /bundle-export/trained-model

Triggers the export process that creates an Asset Bundle for a specified trained model.

The export procedure returns the export UUID and the ACCEPTED export status in case of a successful export. When an error occurs, the export status is FAILED. Exact errors are listed in the errors property.

Parameters

• modelName: UUID of the trained model to be exported
• name: Optional; name of the bundle to be exported
• description: Optional; description of the exported bundle

Request example

curl --request POST \
   --url https://host/workfusion/api/v1/bundle-export/trained-model/ \
   --header 'X-CSRF-TOKEN: 60bec5f5-29ce-4bdc-bb0b-3c352265ef50'
   --header 'cache-control: no-cache'
   --data modelName=assignment_property_10

Successful response example

{
    "uuid": "a91bc45a7-8acb-4466-bdb6-f434f6d1b3e4",
    "status": "ACCEPTED",
    "errors": [],
    "warnings": []
}

Failed response example

{
    "uuid": null,
    "status": "FAILED",
    "errors": ["Trained model with specified model name is not found assignment_property_10"],
    "warnings": []
}

GET /bundle-export/{uuid}

Looks up for the export status. Returns the bundle export status information.

Request example

curl --request GET \
  --url http://host/workfusion/api/v1/bundle-export/c6771931-70bd-49c5-bff0-addc990e9e40 \
  --header 'X-CSRF-TOKEN: a74cda5f-cd3b-4a32-a8e5-074a2ad5664a' \
  --header 'cache-control: no-cache'

Successful response example

{
"uuid": "d29ce4e6-a1c0-4c42-8550-eacc59b3a5de",
"status": "SUCCEEDED",
"path": "d29ce4e6-a1c0-4c42-8550-eacc59b3a5de/deed_seller_10.zip",
"errorMessage": null
}

GET /bundle-export/download/{uuid}

Downloads Asset Bundles. Returns 404 in case an Asset Bundle is not ready.

Request example

curl --request GET \
   --url https://host/workfusion/api/v1/bundle-export/download/f57aa7ac-3f2f-48bb-bbe7-6dd958ff44e4
   --header 'X-CSRF-TOKEN: 60bec5f5-29ce-4bdc-bb0b-3c352265ef50'
   --header 'cache-control: no-cache'
   --output 'output.zip'

Windows 10 cURL example

Windows 10 is shipped with the cURL utility, but its syntax differs from that of Linux commands. The example below shows how to execute cURL requests on the Windows machine:

1. Log in. Make sure you can create and edit the file inside the target location without Administrator rights. It is created automatically.

   curl -X POST -d "j_username=username&j_password=password" -H "Connection: keep-alive" -c "C:/Users/user1/cookie.txt" https://workfusion-lb.wf.tc.ab.zz/workfusion/api/dologin
   

2. To import an Asset Bundle, insert the token you received from the previous response instead of <token>:

   curl -X POST -H "X-CSRF-TOKEN: <token>" -H "Connection: keep-alive" -H "cache-control: no-cache" -H "content-type: multipart/form-data" -b "C:/Users/user1/cookie.txt" -F "bundleFile=@C:/Users/user1/usecase-package-21.09.017.zip" https://<instance-name>/workfusion/api/v1/bundle-import/
   

3. To check the import status, insert the import UUID you received from the previous response instead of <import_uuid>.

   curl -X GET -H "X-CSRF-TOKEN: 9f4a4ca1-6d32-4c66-acd7-c157892c56df" -H "Connection: keep-alive" -H "cache-control: no-cache" -b "C:/user1/060156/cookie.txt" https://<instance-name>/workfusion/api/v1/bundle-import/<import_uuid>