Transform documents APIs

This feature is only enabled on certain environments and tenants. Contact support for more information about this feature.

Authorization

• Bearer {token} accessible from Authorization - Bearer token or systematically via Client credentials.

  • The request headers should include a key for Authorization with the value Bearer {token}.

Upload transform document file

POST /{tenant}/api/v4/transforms/{transform_folder}

Add a new transform document to the specified folder based upon the transform filename. The document will be checked against the Validate transform endpoint. If the transform already exists, a new version of the transform will be added.

Path parameters

Key	Value
tenant *	Tenant is part of your sign-in URL and also available in the User menu.
transform_folder *	Target folder name.

Request body

Content-Type: multipart/form-data

Key	Value
file	Transform document. The filename must end with _transform.json.

Sample request and response

Sample request

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/myfolder' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"/C:/myfolder/mytransform_transform.json"'

Sample response

HTTP 200 OK Content-Type: application/json

{
    "object": "transform",
    "response_timestamp": "2024-11-15T03:46:33.5680069Z",
    "process_time": 898,
    "id": "2cadfd08-058d-41a5-8926-c92a3f548bdd",
    "status": "added",
    "outputs": {
        "name": "mytransform",
        "transform_uri": "myfolderg/mytransform"
    }
}

Add transform with document content

POST /{tenant}/api/v4/transforms/{transform_folder}/{transform}

Add a new transform to the specified folder with the transform name using the content transform document that is included in the request body. The document will be checked against the Validate transform endpoint. If the transform already exists a new version of the transform will be created.

Path parameters

Key	Value
tenant *	Tenant is part of your sign-in URL and also available in the User menu.
transform_folder *	Target folder.
transform *	Target transform document name.

Request body

Content-Type: application/json

Key	Value
transform_content	The entire contents of the in a single string. Ensure the content is properly escaped. Content within transform definitions such as input_body_transform or output_body_transform may need to be double escaped, e.g. " becoming \".

Sample request and response

Sample request

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/mytransformname' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
    "transform_content": "{\"transform_type\": \"JSONtransforms_v2.0.1\", \"target_api_version\": \"v3\", \"input_body_transform\":\"{\\\"add_1\\\":add.a,\\\"add_2\\\":add.b,\\\"multiply_1\\\":multiply.a, \\\"multiply_2\\\":multiply.b}\", \"output_body_transform\":\"{\\\"add\\\":{\\\"result\\\":response_data.outputs.add},\\\"multiply\\\":{\\\"result\\\":response_data.outputs.multiply},\\\"meta\\\":{\\\"id\\\":response_meta.call_id}}\"}"
}'

Sample response

HTTP 200 OK Content-Type: application/json

{
    "object": "transform",
    "response_timestamp": "2024-11-15T03:46:33.5680069Z",
    "process_time": 898,
    "id": "2cadfd08-058d-41a5-8926-c92a3f548bdd",
    "status": "added",
    "outputs": {
        "name": "mytransform",
        "transform_uri": "myfolder/mytransform"
    }
}

Validate transform

POST /{tenant}/api/v4/transforms/validation

This API performs the following validations:

• The transform is valid JSON.

• transform_type is present and valid.

• Other checks are specific to the transform being used.

Path parameters

Key	Value
tenant *	Tenant is part of your sign-in URL and also available in the User menu.

Request body

Content-Type: application/json

Key	Value
transform_content	in a single string. Ensure the content is properly escaped. Content within transform definitions such as input_body_transform or output_body_transform may need to be double escaped, e.g. " becoming \".

Sample request and response

Sample request

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/validation' \
--header 'Content-Type: application/json' \
--header 'Authorization: {token}' \
--data '{
    "transform_content": "{\"transform_type\": \"JSONtransforms_v2.0.1\", \"target_api_version\": \"v3\", \"input_body_transform\":\"{\\\"add_1\\\":add.a,\\\"add_2\\\":add.b,\\\"multiply_1\\\":multiply.a, \\\"multiply_2\\\":multiply.b}\", \"output_body_transform\":\"{\\\"add\\\":{\\\"result\\\":response_data.outputs.add},\\\"multiply\\\":{\\\"result\\\":response_data.outputs.multiply},\\\"meta\\\":{\\\"id\\\":response_meta.call_id}}\"}"
}'

Sample response

HTTP 200 OK Content-Type: application/json

{
    "object": "transform",
    "response_timestamp": "2024-11-15T04:20:11.2557602Z",
    "process_time": 0,
    "id": null,
    "status": "complete",
    "outputs": {
        "isValid": false,
        "error": [
            {
                "code": "TRANSFORM_DEFINITION_ERROR",
                "type": "invalid_input",
                "message": "'JSONtransforms_v2.0.1' is not a valid transform_type. Valid entries are (JSONtransforms_v1.0.1)."
            }
        ]
    }
}

List transforms

POST /{tenant}/api/v4/transforms/list/{folder}

Path parameters

Key	Value
tenant *	Tenant is part of your sign-in URL and also available in the User menu.
folder *	Folder associated with the request.

Request body

Content-Type: application/json

Key	Value
page	Page number of the list to get.
pageSize	Number of records per page.
sort	String defining the sort order. Example: -updated
search	Array of search filter objects. Search filter objects can include: field Name of the field to filter. value Value of the field to filter. operator Applies to numeric properties. Example 1: {"field": "name", "name": "myfoldername"} Example 2: {"field": "isstarred", "isstarred": "true"}

Sample request and response

Sample request

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/list/myfolder' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
    "page": 1,
    "pageSize":15,
    "sort": "-updatedAt,-name"
}'

Sample response

HTTP 200 OK Content-Type: application/json

{
    "count": 2,
    "page": 1,
    "pageSize": 15,
    "result": [
        {
            "id": "122392a3-0ce1-44d0-869a-33551034d1c3",
            "name": "mytransform1",
            "transform_type": "JSONtransforms_v1.0.1",
            "updatedAt": "2024-11-15T04:12:23.056031Z",
            "modifiedBy": "[e-mail]",
            "createdBy": "[e-mail]",
            "createdAt": "2024-11-15T04:12:23.05603Z"
        },
        {
            "id": "a481ec59-fd75-40b0-9e6c-4edbc06dc3bc",
            "name": "mytransform2",
            "transform_type": "JSONtransforms_v1.0.1",
            "updatedAt": "2024-11-15T04:05:13.055016Z",
            "modifiedBy": "[e-mail]",
            "createdBy": "[e-mail]",
            "createdAt": "2024-11-15T04:05:13.055015Z"
        }
    ]
}

Get transform document

GET /{tenant}/api/v4/transforms/{transform_folder}/{transform}

Path parameters

Key	Value
tenant *	Tenant is part of your sign-in URL and also available in the User menu.
transform_folder *	Folder associated with the request.
transform *	Transform document associated with the request.

Sample request and response

Sample request

curl --location 'https://excel.myenvironment.coherent.global/coherent/api/v4/transforms/myfolder/mytransform' \
--header 'Authorization: Bearer {token}'

Sample response

HTTP 200 OK Content-Type: application/json

{
    "object": "transform",
    "response_timestamp": "2024-11-15T04:29:17.0825837Z",
    "process_time": 73,
    "id": "212a2adc-dd5a-417d-a623-5a45d5ba2fa7",
    "status": "success",
    "outputs": {
        "transform_document": "{\n    \"transform_type\": \"JSONtransforms_v1.0.1\",\n    \"target_api_version\": \"v3\",\n    \"input_body_transform\": \"{\\r\\n  'add_1':add.a,\\r\\n  'add_2':add.b,\\r\\n  'multiply_1':multiply.a,\\r\\n  'multiply_2':multiply.b\\r\\n}\",\n    \"output_body_transform\": \"{\\r\\n  'add':{'result':response_data.outputs.add},\\r\\n  'multiply':{'result':response_data.outputs.multiply},\\r\\n  'meta':{'id':response_meta.call_id}\\r\\n}\"\n}",
        "updatedAt": "2024-11-11T05:46:33.46664Z"
    }
}

Delete transform

DELETE  /{tenant}/api/v4/transforms/{transform_folder}/{transform}

Path parameters

Key	Value
tenant *	Tenant is part of your sign-in URL and also available in the User menu.
transform_folder *	Folder associated with the request.
transform *	Transform document associated with the request.

Sample request and response

Sample request

curl --location --request DELETE 'https://excel.myenvironment.coherent.global/coherent/api/v4/transforms/myfolder/mytransform' \
--header 'Authorization: Bearer {token}'

Sample response

HTTP 200 OK Content-Type: application/json

{
    "object": "transform",
    "response_timestamp": "2024-11-15T04:35:50.1175746Z",
    "process_time": 130,
    "id": null,
    "status": "deleted",
    "outputs": {
        "name": "mytransform",
        "transform_uri": "myfolder/mytransform"
    }
}