This is sent as a POST call.

The body of the call to create a workset with two data views is shown below. Note that the ‘data views’ section of the entity portion of the body is an array and needs to follow JSON formatting rules for an entity.

{
    "context": {
        "user": "mbj_test",
        "password": "xxxx",
        "project": {
            "name": "imp_payments_demo",
            "version": "1.0"
        }
    },
    "entity": {
        "name": "api_workset",
        "scenario": {
            "name": "imp_make_payment",
            "version": "1.0"
        },
        "primary": {
            "view": {
                "name": "format_cov_view",
                "version": "1.0"
            },
            "dataSet": {
                "name": "api_demo_coverage",
                "version": "1.0.0"
            }
        },
        "dataViews": [
            {
              "view": {
                "name": "cust_data_view",
                "version": "1.0"
            },
            "dataSet": {
                "name": "imp_customers",
                "version": "1.0.0"
            }
            },
            {
              "view": {
                "name": "acts_view",
                "version": "1.0"
            },
            "dataSet": {
                "name": "imp_accounts",
                "version": "1.0.0"
            }            
            }            
        ]
    }
}

The return message shows the status of the call as well as the details of the workset that has been created.

The created workset can now be viewed in the worksets page of TDO. When you enter edit mode for this workset you can see the workset details in this page match the parameters sent in the body of the call.

This API is used to update worksets, either by changing the datablock underlying the data view or by adding a new data view. It is sent as a PATCH call.

There is one difference between the body of the ‘create’ and ‘update’ calls. The first is that the initial part of the ‘entity’ section [defines the workset name, the primary data view, and underlying coverage set] is replaced by a single line, ‘id’, that contains the TDO id for the workset being upated. This id can be found in the return message of the create, get all, and get details APIs.

Also, to perform the update, you need to be making a change. Here, we have changed the name of the data block underlying the customer data view from ‘imp_customers 1.0.0’ to ‘customers 1.0.0’. We have also added a new data view, ‘clh_view’ to the workset.

{
    "context": {
        "user": "mbj_test",
        "password": "xxxx",
        "project": {
            "name": "imp_payments_demo",
            "version": "1.0"
        }
    },
    "entity": {
       "id": "6761ae6d98cd8a04d7f4e959",
        "dataViews": [
            {
              "view": {
                "name": "cust_data_view",
                "version": "1.0"
            },
            "dataSet": {
                "name": "customers",
                "version": "1.0.0"
            }
            },
            {
              "view": {
                "name": "acts_view",
                "version": "1.0"
            },
            "dataSet": {
                "name": "imp_accounts",
                "version": "1.0.0"
            }            
            },
            {
              "view": {
                "name": "clh_view",
                "version": "1.0"
            },
            "dataSet": {
                "name": "clh_view",
                "version": "1.0.0"
            }            
            }                      
        ]
    }
}

The return message contains the information on what was sent to TDO, including the updated views. The workset id (in the response message) has remained the same, but the workset version is now returned as ‘1.1’.

Looking at the workset in TDO, we can see the changes that were made to the workset. The version has incremented to 1.1, the file for ‘cust_data_view’ has changed, and the ‘clh_view’ has been added to the workset.

These calls can be used to create, update, delete, get all, get details, clone, and unlock worksets. The URL’s and call types are listed in the table below.

For the create and update API’s, the body fields are needed to provide the necessary context. A list of these fields and which call they are required for is provided below.

This call returns a list of all of the worksets in any given project. It is POST call.

The body for this call is very simple, containing only the user credentials and the project name.

{
          "context": {
                    "user": "mbj_test",
                    "password": "xxxx",
                    "project": {
                              "name": "mug_test_project",
                              "version": "1.0"
                    }
          }
}

When run, the return message shows all of the worksets in this project.

This call is used to remove a lock placed on a workset. In TDO, you can see that the workset ‘api_workset’ has a lock placed by user ‘mbj_test’. Note that locks can be removed under two circumstances: the user who placed the lock can remove their own lock. In addition, an Admin user can remove any lock.

NOTE: there is no API call to place a lock on a workset; this lock is placed when you run the data assembly process (either via the UI or API).

This API is sent as a PATCH call. The call includes the instruction ‘unlock’ and the id of the workset to have the lock removed.

The body is the same as the body for the Get Details API.

The return message shows that the lock has been removed (last fields) where the ‘lockedBy’ and ‘lockDateTime’ fields are blank/null and the ‘lockTimeout’ is ‘-1.

This API will create a copy of the workset with the new name specified in the API call. It is run as a POST call and adds a variable for the new workset name to the call used to get workset details (ie, after 'workset' the API includes the instruction 'clone' and then the ID of the workset being cloned and the name of the new workset being created).

The API looks like the example below.

https://<server>:<port>/core/API/workSet/clone/<workset_id>?name=<new_name>.

For example, it would be: https://localhost:8080/core/API/workSet/clone/6761ae6d98cd8a04d7f4e959?api_clone_workset.

When creating this url, remember to use a new name ending in '_workset'.

In this case, we are cloning the workset ‘api_2_workset’ shown below.

The body of this call is still the very simple body (user ID, password, and project).

When run, the response shows the details of the cloned workset.

This call returns details on a specific workset. It is very similar to the ‘Get all Worksets for Project’ call, with the exception of having the workset’s TDO id in the call.

The body for this call is the same as the body for ‘get all worksets’.

 {
    "context": {
        "user": "mbj_test",
        "password": "xxxx",
        "project": {
            "name": "imp_payments_demo",
            "version": "1.0"
        }
    }
}

The return message contains the details for the requested workset.

These details can be compared to the details shown in the ‘Edit Workset’ screen on TDO.

This API deletes an existing workset. As the workset ID is passed in the URL, you can only delete one workset at a time. It is run as a DELETE call. This API can only be run by a user with Admin privileges; all other users will get a return message that they do not have proper authorization to perform this function.

The body is the same body as the other simple calls (other than ‘create’ and ‘update’).

 {
    "context": {
        "user": "mbj_test",
        "password": "xxxx",
        "project": {
            "name": "imp_payments_demo",
            "version": "1.0"
        }
    }
}

Here is the workset listing prior to running this call. The ID in the call URL is for the ‘cloned_workset’.

When run, the response contains the result (‘0’ for false and ‘1’ for true). A response of ‘1’ indicates that the workset has been deleted.

When viewing the workset listing in TDO, the workset ‘cloned_workset’ is no longer present.