Within each functional area, the API’s are capable of:

· Create new item

· Get all items (needed to get the internal ID for any item you want to update, get details, or delete)

· Update item

· Get item details

· Delete item

· Lock/Unlock item (Coverage Sets and Work Sets)

In order to execute any of these functions: update, delete, get item details, lock, or unlock you need to first run the ‘get all’ API to get the item’s internal ID which is then sent in the action API.

In this document, Postman (free version) is used to demonstrate how each API should be set up and used and show the expected response formats.

General API information

Each request must have a body that includes credentials [required], project name/version [required], and entity definition [optional]. Each API will be covered in detail within the specific section devoted to that action.

The context object is used to provide TDO authentication data and project information. For Business Rule API’s the Coverage Set information must also be passed in the context object. The context object is a JSON object that must be included in the request body.

Specification:

Example:

{

"context": {

"user": "tdo_api_user",

"password": "welcome",

"project": {

"name": "api_testing",

"version": "1.0"

},

"coverage": {

"name": "api_testing_coverage",

"version": "1.0"

}

}

}

Authentication

TDO will authenticate the credentials presented by the API using the following algorithm, based on what authentication protocol is active:

· Basic TDO form authorization – credentials are set up in TDO

· LDAP – credentials will be passed to LDAP by TDO and validated in LDAP

· SAML – user with name/password must exist in TDO and will be authenticated in TDO

Note that for the ‘Delete’ API’s, TDO only allows the ‘Admin’ role to perform deletions. The API’s do not override this requirement, so to perform the delete functions you must use credentials that are enrolled as Admin. If you send credentials that are enrolled as User, you will receive an error message that you do not have the right authority to perform that function.

Entity Object

Entity Object defines the entity the API will process. Entity must contain one of the following attributes – name (create request) or id (update request). (Create determining attribute entity is shown below for reference.)

"entity": {

"name": "acct_type",

"dataType": "STRING",

"type": "VALUE",

"values": [

"Checking", "Savings", "Current"

}

In all of the tables in the detail sections, the URLs shown should be preceded by the identifying server information (http(s):<server_name>:8080, for instance). The format for this will be specific to your installation.

The following actions can be performed via API’s for determining attributes.

The Create action can create two types of determining attribute: a range based attribute (ex: 1 – 100, 101 – 200, etc) or a value based attribute sourced from a data block. These are two separate API’s.

The Get all DA’s for project API will return the determining attribute names and id’s. In order to run the Update, Delete, or Get DA details actions, you must first run this action to get the id for the action you want to work with.

The Update API can be used to add additional values to a determining attribute or to add/change priorities assigned to those values.

The Delete API will delete the specified determining attribute.

The Get DA details API will pull all details associated with the specified determining attribute.

The tables below show both the required and optional items in the Create and Update requests. Note that some of these vary between a value-based determining attribute and a range-based determining attribute.

Value-based determining attribute:

Range-based determining attributes contain the same fields as the value-based API but with a different format for the entity.values [ ] field. In this case, you must send both a minValue and a maxValue; if you do not sent both for a range-based entity the API will fail.

In the example shown below, we are creating a determining attribute called ‘amount_1’ as a numerical range determining attribute, with 3 values: 0 – 250, 250.01 – 2500, and 2500.01 – 25000. We are creating this in the ‘imp_payments_demo’ project, version 1.0

The API is defined as

Where ‘http://99.99.99.99:8080/ is the protocol://server:port where TDO resides.

{

"context": {

"user": "mj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

},

"entity": {

"name": "amount_1",

"dataType": "NUMBER",

"type": "RANGE",

"values": [

{

"minValue": 0.01,

"maxValue": 250

},

{

"minValue": 250.01,

"maxValue": 2500

},

{

"minValue": 2500.01,

"maxValue": 25000

}

]

}

}

This screen print shows the results code in Postman. You will also note that the parameters screen is set up with the type of call (POST) and the full URL for the call (server name/port + URL from the initial table).

Here is how the determining attribute looks in TDO.

This API can be used to create one determining attribute. The determining attribute can be sourced from an imported data block or can be standalone (meaning no data block source). The examples below show how the API should be laid out for each option.

No Data Block Source

In this API, the ‘entity’ values are passed to create a new determining attribute named “currency_a”. Since there is no underlying data block, the entity source is not identified.

The API is still defined the same way as for a range-based determining attribute:

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

},

"entity": {

"name": "currency_a",

"dataType": "STRING",

"type": "VALUE",

"values": [

"USD", "GBP", "EUR"

]

}

}

The results screen from Postman shows the API was created.

An ID for the determining attribute is provided in the results section. If you are going to update or delete this determining attribute, you will need this ID. (Note that the ID can also be found in the ‘Get all DAs’ API.) This is the attribute in TDO after it has been created by API.

Data Block Used as Source

The data block to be used as the source must already exist in TDO to run this API. It is the same as the API above, except that the entity.source .name and entity.source.version are also included in the API. You will want to link a determining attribute to an underlying data block if you intend to filter the attributes at a later date. This filtering is performed using the entity.criteria field.

The url is the same as for the no data block source API call. The body contains additional information.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

},

"entity": {

"name": "acct_type",

"dataType": "STRING",

"type": "VALUE",

"values": [

"Checking", "Savings", "Current"

],

"source": {

"name": "imp_accounts",

"version": "1.0",

"attribute": "account_type"

}

}

}

When this API is run, the results screen in Postman shows the following.

As with other successful calls, the ID for the new determining attribute is returned with the message.

In the TDO UI, the new determining attribute displays the linked data block and field (top portion of screen) in addition to the attribute values.

Several types of updates can be performed using this API. You can add more values to the attribute, you can add priorities to the determining attribute, and you can set filters on determining attributes. Note that these are run as ‘PATCH’ for updates, as opposed to ‘POST’ for creation.

Setting Priorities

This example shows using the valuesPriority option to set priorities on previously created attributes.

Here, we use the id for the determining attribute in the entity section to identify it as an existing attribute. This can be found in the response of the Create Determining Attribute API or in the Get DA Details API. We also identify the values of the determining attribute that we want to set priorities for (this DA has only two values). In the valuesPriority section, we list the value and the associated priority.

The API call is the same protocol://server:port as above, but it is defined as ‘PATCH’ instead of ‘POST’ for this process.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

},

"entity": {

"id": "645e0000390613152b16ecbb",

"values": [

"0",

"1"

],

"valuesPriority": {

"0": "1",

"1": "2",

}

}

}

Here is the Postman screen after the API has been run showing that the priorities were set.

And here is the edit determining attributes screen from the TDO UI, showing the priorities assigned to the values.

Group by Settings for Attributes

Group by for determining attributes is a process in TDO that allows you to enforce valid combinations of data – for instance, I can choose to group ‘has_app’ by ‘customer_type’. In this demo database, customers with a customer type of ‘Retail’ can have the value of ‘0’ [false] or ‘1’ [true] for ‘has_app’ but customer type of ‘Corporate’ can only have the value of ‘0’. By adding the group by, I make sure that if I select the ‘Corporate’ customer type, only the ‘false’ option will display for has_app, preventing a user from selecting an invalid option (‘true’) in error.

Group by will only work for fields that are in the same source data block; you cannot group by a field that exists in a different data block as there is not relationship defined for TDO to refer to. The determining attribute is identified by it’s id number. The attribute values are listed. Then in the criteria section, each value has the ‘group by’ attribute identified.

The API is defined the same as for setting priorities. The body is similar, except that the 'group by' field is listed in the criteria section of the body instead of the 'priority'.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

},

"entity": {

"id": "645e0000390613152b16ecbb",

"values": [

"0",

"1"

],

"criteria": {

"0": "customer_type",

"1": "customer_type",

}

}

}

When run, Postman shows the results as below.

In TDO, you can now see the group by results. The column on the right in the bottom section of the screen below (Determining Attribute) is the column that the Data Block Attribute (on the left) is grouped by. Note that since this update was performed on an attribute that already had priorities set, those are also shown in the return message.

This can be run two ways – one will return all details for a single determining attribute, and the other will return details on all determining attributes in a project.

For the single attribute details, you need the attribute ID to run the API. So we will look at the ‘all determining attributes’ process first, as that will provide the determining attribute ID.

Get all Details

For returning details on all determining attributes, the API call is defined as POST (the same as for creating determining attributes.

The body of the message is very simple, just listing the credentials and the project.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

The response in Postman shows the details for all determining attributes in this project.

Get Single Attribute Details

We will use the first determining attribute (‘has_app’) for the single determining attribute call. The ID for this attribute is 645e0000390613152b16ecbb. To set the call for a single determining attribute, it is defined as above, but with the attribute ID appended at the end of the call.

The body of the message remains the same as the ‘all attributes’ call.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

And here you can see that the return message only has the details on the determining attribute we defined in the API.

You can delete determining attributes one at a time using this method. The call is defined as ‘DELETE’ instead of ‘POST’ or ‘PATCH’.

The determining attribute ID shown above is for the ‘data_block_based’ seen below.

Prior to deletion, you can see the determining attribute in TDO.

The body of the message is the same as for ‘get details’ API’s.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

When run, the message only shows the successful completion of the call.

Checking the determining attributes list in TDO, this attribute is no longer present.

Remember, only users with administrative credentials can delete objects in TDO.

As with Determining Attributes, you can perform the ‘create’, ‘update’, ‘get all’, and ‘delete’ actions. You can also perform the ‘lock’ and ‘unlock’ actions on Coverage Sets via API calls. [Locking a coverage set prevents other users from changing it while you are working on it, and the unlock action removes the lock so that it is available for another user to work with it.]

The list of Coverage Set API’s is shown in the table below.

The list of fields used in the API’s is shown below, along with when/where they are required.

The first action to take on coverage sets is to create a new coverage set. This can be done for one or more determining attributes. The call is set up as a POST call.

The body of the call contains the project name and version and credentials in the ‘context’ section. In the entity section, you provide the name of the coverage set you are creating (it must end with ‘_coverage’) and the determining attribute name(s)/version(s) you want to include.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

},

"entity": {

"name": "api_demo_coverage",

"determiningAttributes": [

{"name": "acct_type", "version": "1.0"},

{"name": "has_app", "version": "1.0"},

{"name": "has_online", "version": "1.0"},

{"name": "balance", "version": "1.0"}

]

}

}

When this is run, a successful return message will show the return code (200) as well as the information on the coverage set created by this call.

When the coverage set is viewed in the TDO UI, you can see the determining attributes linked to this set.

Before you update a coverage set, you need to lock it. This can be done via the Lock Coverage Set API.

This API is sent as a ‘PATCH’ to update an existing coverage set.

In the body of the call, you need to include the ID of the coverage set (instead of name/version). This can be obtained from the return message on the ‘create’ or ‘get all’ APIs. You can use this to add or delete determining attributes. To add determining attributes, include all of the existing attributes plus the ones you want to add. To delete determining attributes, only include the ones you want to keep and exclude the ones you want to delete.

Adding one or more determining attributes

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

},

"entity": {

"id": "6744c4ee59c7b96171b5a827",

"determiningAttributes": [

{"name": "acct_type", "version": "1.0"},

{"name": "has_app", "version": "1.0"},

{"name": "has_online", "version": "1.0"},

{"name": "balance", "version": "1.0"},

{"name": "currency_a", "version": "1.0"},

{"name": "customer_type", "version": "1.0"}

]

}

}

When this is run, the successful return message will show all attributes in the coverage set.

This shows the updated coverage set in TDO. Note that the updated set is now version 1.1 (the original version still exists with 4 attributes) and contains all six attributes sent in the API. TDO increments the version upwards automatically, so the user should not manually update or increment versions.

Deleting One or More Attributes

The delete call remains the same as the add call. Note that you could combine both actions in a single call, by excluding the attributes you want to delete and including the ones you want to add. In this message, we have removed the ‘balance’ attribute from the set. Also note that the coverage set ID has changed. The value used in the update/add call (6744c4ee59c7b96171b5a827) is still the ID for version 1.0 of this coverage set. The value used below is the value for version 1.1, which is the version we are updating.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

},

"entity": {

"id": "6745f4c559c7b96171b5a82a",

"determiningAttributes": [

{"name": "acct_type", "version": "1.0"},

{"name": "has_app", "version": "1.0"},

{"name": "has_online", "version": "1.0"},

{"name": "currency_a", "version": "1.0"},

{"name": "customer_type", "version": "1.0"}

]

}

}

The return message will show the updated contents, as well as the new ID for the new version of the coverage set (1.2).

When viewing version 1.2 in the TDO UI, the ‘balance’ determining attribute is now removed.

All three versions of the coverage set remain in TDO and can be selected and used.

This call is also sent as ‘POST’. It will return information on all coverage sets in the project, including ID.

The body of the call is very simple, just the credentials and project/version.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

The return message contains the details for all coverage sets in this project (there are six in this project). Note that the return message contains IDs and details for the coverage sets as well as for all determining attributes in that coverage set. The highlighted section below shows the details for the api_demo_coverage 1.0 set.

This call is used to obtain details on a single coverage set. This call is sent as a ‘POST’. You must know the ID prior to setting this one up as the target coverage set ID is used in the API header.

The body of the call is the same as used for ‘get all coverage sets’.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

The return message contains details only for the requested coverage set.

This call is sent to lock a coverage set in TDO – this will prevent any other user (within the UI or from automated API calls) from making changes to the coverage set or business rules while you are working within that coverage set. It is sent as a ‘PATCH’.

Note that the header is slightly different (it includes the command ‘lock’ in addition to the coverage set ID.

The body of this call remains the same as the ‘get details’ API.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

The return message contains all of the details. Highlighted below is the section of the details around the lock that was placed.

In TDO, the lock can be seen on the main coverage set page; the ID of the user who placed the lock is visible. By hovering the cursor to the right of that ID, you can see the lock icon is also visible.

If you try to place a lock, and the coverage set is already locked by a different user, you will get the return message below, including the ID of the user who has the lock in place.

Once you are finished working in a coverage set, you should release the lock so that other users can access it if desired. The call is very similar to ‘lock coverage set’, except that the command in the header is ‘unlock’ instead of ‘lock’.

The body of the call is the same as in the ‘lock’ call.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

The return message will show the lock attributes removed from the coverage set (highlighted below).

When viewed in TDO, the ‘locked by’ column is now blank for this coverage set (api_demo_coverage 1.0), showing that the lock has been removed.

This call will delete the coverage set from the project. The header is the same as the ‘get coverage set details’ API, except that it is sent as a ‘DELETE’ command. It is recommended that you confirm the ID of the set you are deleting before you run this API as it cannot be reversed.

The body is the same as the simple body API calls; just credentials and project information.

{

"context": {

"user": "mbj_test",

"password": "1234",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

This API will delete the ‘api_demo_coverage 1.0’ coverage set. The return message is very simple, only showing a result of ‘true’.

In TDO, the coverage set main page now shows that ‘api_demo_coverage 1.0’ no longer exists.

Remember only users with administrator credentials can delete objects in TDO.

You can create, update, delete, get details, or get all details for business rules using API’s. This table shows the base API calls.

The fields to be used in the create/update requests are listed below. The get details, get all details, and delete API’s do not require any entity information.

This call will create a new business rule. You can only create one business rule at a time, so if you are creating multiple business rules you will need to run this for each rule.

The API can be used to create a business rule with one or more determining attributes. The key is that the determining attributes referenced in the body of your call must match the determining attributes in the coverage set you are working in. Below, we will show how to create a simple business rule (one determining attribute) and then a more complex rule (multiple determining attributes).

The call for creating the business rule is a POST call.

Simple (one determining attribute)

The body of the call includes the name of the coverage set after the base context (user ID, password, and project). The coverage set you identify must be locked by the user ID you are using to send this API. You will need to send the ‘lock coverage set’ API before creating business rules.

In the ‘entity’ section, you include both the determining attribute name and value(s) in an array. Note that all values selected must exist in the determining attribute as it is defined in TDO.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

},

"coverage" : {

"name": "api_testing_coverage",

"version": "1.1"

}

},

"entity": {

"conditions": {

"account": {

"values": ["Current"]

}

}

}

}

When the rule is created, the return message shows the rule ID as well as the contents of the rule.

Looking at the business rules in this coverage set in TDO, you can see that the rule was set.

Complex (multiple determining attributes)

For this call, we will use the coverage set ‘api_demo_coverage 1.1’. This coverage set has five determining attributes.

The body of the call for multiple determining attributes is set up as an array in the ‘conditions’ section. Note that you can select one or more values for each determining attribute.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

},

"coverage" : {

"name": "api_demo_coverage",

"version": "1.2"

}

},

"entity": {

"conditions": {

"has_app": {"values": ["0"]},

"acct_type": {"values": ["Checking","Savings"]},

"has_online": {"values": ["1"]},

"currency_a": {"values": ["USD"]},

"customer_type": {"values": ["Retail"]}

}

}

}

The response to this call will show all of the attributes you defined in the body of the message.

The business rule now shows in TDO.

This is a PATCH call as opposed to a POST call.

In the body of the message, the ‘entity.ID’ is now a required field. We will update the complex rule created above. The ‘has_online’ determining attribute is being updated to include both ‘true’ and ‘false’ and the ‘currency_a’ attribute is being updated to include both USD and GBP currencies.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

},

"coverage" : {

"name": "api_demo_coverage",

"version": "1.2"

}

},

"entity": {

"id": "674dd0fb59c7b96171b5a8fa",

"conditions": {

"has_app": {"values": ["0"]},

"acct_type": {"values": ["Checking","Savings"]},

"has_online": {"values": ["1","0"]},

"currency_a": {"values": ["USD","GBP"]},

"customer_type": {"values": ["Retail"]}

}

}

}

The return message shows the values that were sent.

In TDO the rule now reflects the new values for ‘has_online’ and ‘currency_a’.

This API gets details on a single business rule in a coverage set. It is sent as a POST. The ID of the rule you want details on is included in the call.

The body of the call includes the context – user ID, password, and coverage set. No other items are required.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

},

"coverage" : {

"name": "api_demo_coverage",

"version": "1.2"

}

}

}

The return message on this API gives all details on the specified rule, including created by, updated by, and all of the conditions.

This API returns details on all rules within a single coverage set. It is sent as a POST, with the same header details as the ‘create’ and ‘update’ calls.

The body of the call looks like the body of the ‘Get Rule Details’ call.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

},

"coverage" : {

"name": "api_demo_coverage",

"version": "1.2"

}

}

}

The return message of the API shows the information for all rules contained in this coverage set.

This coverage set now contains three rules; the information on all three is included above. In TDO, the three rules are also shown.

This call is sent as a DELETE call. You can only delete one rule at a time using this call, as the rule ID is part of the header.

The body of this call is the same as the details calls, only containing the context.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

},

"coverage" : {

"name": "api_demo_coverage",

"version": "1.2"

}

}

}

For this call, we are sending the ID for the third rule in the ‘Get All Details’ call illustrated earlier. The return message simply shows a successful call.

Viewing the business rules in TDO after this call is sent, you can see that the third business rule is no longer present.

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 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.

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 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 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.

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

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.

Viewing the workset screen in TDO after this API has been run, you can see that there is no longer a lock present on this workset (no value in the ‘locked by’ column).

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>

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).

{

"context": {

"user": "mbj_test",

"password": "xxxx",

"project": {

"name": "imp_payments_demo",

"version": "1.0"

}

}

}

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

TDO now shows the cloned workset in the workset listing, and when you edit that workset the details are the same as the one that was cloned.

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.

Two APIs are currently available for the data assembly process: assemble data and check assembly process. These API’s can be called from within an automation program or from a browser window.

This call requires the format of

http://<server>:<port>/core/1.0/API/dataAssemblyRequest/<project_name>/<project_version>/<workset_name>/<workset_version>

Shown below is the call to assemble data for the project mug_test_project 1.0 and mug_test_workset 1.1.

Note that the ID for the data assembly process is shown in the first line.

If you will be calling data assembly and data download from an automation program, you need to be sure that data assembly is complete prior to starting the data download. The check assembly process API will provide current status on data assembly.

The API is sent as a URL only (no body) and can be run from an automation program or from a browser window. The API format is:

http://<server>:<port>/core/1.0/API/dataAssemblyProgress/<worksetID>

The workset ID is returned in the first line of the data Assembly API. The API will return the total progress as a percentage number (100 indicates 100% complete), the number of rows generated, and the total number of rows to be generated.

API’s can be used to ingest (upload) csv files into data blocks in TDO and to download assembled data.

Downloads can be performed in multiple formats; currently they allow for versions from 1.0 to 1.7; each one will be covered individually.

Currently, only csv files can be ingested by TDO. These files must meet some simple rules:

· Each file must contain column headers in the first row, and at least one row of data.

· The column header field names must be lower case only, and use underscores instead of spaces.

· Files cannot contain commas. This is due to rules governing csv files, which interpret a comma as a field delimiter. Including a comma in a field will cause it to be split into two fields upon ingestion and all subsequent fields in that row will be out of sync with the column headers.

Data upload is sent as two separate API’s, first a POST request to load the data and create an object ID in TDO and then a PUT request to provide the object names in TDO.

There are two ways to send the data file to TDO - by pasting it in the body of the POST request, or by identifying the path/file in the body of the post request.

Regardless of the method used to move the data into TDO, the POST request must always be followed by a PUT request that links the uploaded data to a specific project, file name, and data block name.

Including data in the body of the POST request

The file contents are the body of the message for the POST request, and for the PUT request the body must contain the file name and the data block name. If this is a new upload, that is all that is needed. If this is a refresh of an existing data block then you may also include a third line in the body, with a version number for the existing data block that is to be updated. If you do not include a version number, TDO will assign the the next sequence number available (i.e., 1.0 for a new data block name, 1.n for an existing data block).

The POST request format is http://<server:port>/core/1.0/API/upload.

The return message contains the UUID for the object as well as the sample for the second API.

Identifying the path/file in the POST request

The format of the request remains the same (URL). In your automation tool (Postman is used here to demonstrate) select 'binary' as the format for the body of the request. A 'select file' box will be displayed. Click on the '+' sign next to 'New file from local machine' and a file explorer/file selection window will open. Navigate to the desired file, highlight it, and click 'Open' and the file name will populate in the window.

Note that any automation program that supports binary as an input option in the body (e.g., Insomnia, Postman, etc.) will support this process.

Click 'Send' to run this call, and you will receive the same return message as shown above.

PUT Request to identify data in TDO

The second API URL is http://<server:port>/core/1.0/API/project/<project-name>/<project-version>/upload/<file-id>.

In Postman, the header line, body, and response for a new file put will look like the below example. TDO will automatically version the upload - if this data block ('test3_block') already exists as version 1.0, TDO will assign version 1.1 to your uploaded data. If this data block name is new in the project, TDO will assign version 1.0.

After this is run, you can see the resulting data block in TDO. You will not be able to see the data block in TDO until this call is completed; this is what associates the data to a specific project and data block name.

The contents of the data block can be viewed in TDO.

Data can be exported in multiple formats, controlled by the API version.

· 1.0 = html

· 1.1 = csv

· 1.2 = comma delimited with sequence numbers (output as .txt format)

· 1.3 = pipe delimited

· 1.4 = tab delimited with sequence numbers

· 1.5 = EDI X12 834 message format

· 1.6 = SQLlite database

· 1.7 = ALIGHT file format (health insurance enrollments)

The format of the download API for methods 1.0 through 1.4 and 1.6 is http://<server:port>/core/<api_version>/API/project/<project_name>/<project_version>/datablocks/<data_block_name>/<data_block_version>/

Methods 1.5 and 1.7 have their own download format which will be covered in the applicable section.

These files can be requested manually by placing the API call in a browser window, or using automation programs. The examples below show the output in a viewable editor format, but these files can be pulled into an automation program instead of viewing them manually.

This can be run from any browser tab or within any automation program. The file will be the return message.

This can be run directly from your automation tool or from a browser window.

The request is in the format http://99.99.99.99:8080/core/1.0/API/project/mug_test_project/1.0/datablocks/request_7_step/1.1/ which is pointing to the mug_test_project 1.0 and request_7_step 1.1 datablock.

Shown below is the format in a Chrome tab.

To request the same file as a csv, you simply change the API version to 1.1.

This can be run directly from your automation tool or from a browser window.

http://99.99.99.99:8080/core/1.2/API/project/mug_test_project/1.0/datablocks/request_7_step/1.1/

When run in a browser tab, the browser download manager will show when the file is available.

The file can be accessed and opened via the download manager.

This file is output as a .txt format file. To obtain a this file, the API version is changed to 1.2. This format is used by some automation tools.

This can be run directly from your automation tool or from a browser window.

http://99.99.99.99:8080/core/1.2/API/project/mug_test_project/1.0/datablocks/request_7_step/1.1/

The file download, if run from a browser tab, will be available via your browser download manager.

Once the download is complete, use download manager to view the output in a text editor.

This format is used with some automation programs, including Cucumber. Change the API to version 1.3. This can be run directly from your automation tool or from a browser window.

http://99.99.99.99:8080/core/1.3/API/project/mug_test_project/1.0/datablocks/request_7_step/1.1/

As above, you can use the download manager to view the output in a text editor.

This format is most often used with automation programs. To call this format, change the API version to 1.4.

This can be run from automation tools or from a browser window.

http://99.99.99.99:8080/core/1.0/API/project/mug_test_project/1.0/datablocks/request_7_step/1.1/

Viewed in a text editor, the output is tab delimited.

This message is used exclusively in the Health Insurance arena. Message formats currently exist for all states using the federal platform ( as well as the state based exchanges for CA, CO, GA, and WA.

The API format for 834 files is 1.5. Also important to note is that while you must end the URL with a “/” for the standard output formats, you must not use a terminal slash on this version.

http://<server:port>/core/1.5/API/project/<project_name>/<project_version>/datablocks/<datablock_name>/<datablock_version>/<template>/<record_output>

For this call, there are two additional items to know.

· <template> - this identifies which state template to use.

o or = any state on the federal platform

o ca = California

o co = Colorado

o ga = Georgia

o wa = Washington

· <record_output> - you can choose to output only a specific row or you can ouput the entire file

o -1 = output entire file

o 0 = output row 1

o 1 = output row 2

o n = output row n-1

To output a full file for Georgia (this project is specifically designed to generate Georgia 834 enrollment files) the URL is:

http://99.99.99.99:8080/core/1.5/API/project/gga_834_project/1.0/datablocks/gga_or_fam_834/1.1/ga/-1

The browser download manager may identify this as an insecure file type; you will manually have to click ‘Keep’ in the download manager to get the file.

This is a sample of the file output by TDO:

The API format for SQL Lite database output is the same as the other standard formats (1.0 - 1.4); the only difference in the URL is changing the API version to 1.6.

http://99.99.99.99:8080/core/1.6/API/project/mug_test_project/1.0/datablocks/request_7_step/1.1/

This file is managed by the browser download manager and can be viewed in any database manager that supports SQL Lite.

This message is used exclusively in the Health Insurance arena, generally for employer provided insurance. Alight supports both a 2500 byte and a 1500 byte file; currently only the 2500 byte file format is available in TDO.

The API format for this Alight file is 1.7. Also important to note is that while you must end the URL with a “/” for most of the versions above, you must not use a terminal slash on this version. Also, this is the only data assembly call where you use the workset name and not the datablock name to identify the source.

The URL format is http://<server:port>/core/1.7/API/project/<project_name>/<project_version>/<workset_name>/<workset_version

One of the main differences between the 834 format and the Alight format is that in the 834, each subscriber/family is a single set while in the Alight format each individual is a record; subscribers and family members are differentiated by the record type indicator. Because of this each family member is set up in a different step in TDO. So the data assembly processes the entire workset (all steps) in one call and determines which family members to include based on their record indicator type.

To output a file for employer ‘ACME INC’ the URL would look like this:

http://99.99.99.99:8080/core/1.7/API/project/alight_project/1.0/t_enroll1_workset/1.0

TDO assigns the file name based on the employer name and processing date. The output from this file is shown below.

There are 5 reporting API’s available. The table below shows the API’s and the associated parameters.

This API can be sent from an automation tool, such as Postman, or can be run directly in a browser window.

The API format contains the server/port/api information, followed by a question mark and then the parameters.

https://<server>:<port>/<api_url>?parameter1=<value>&parameter2=<value>

As an example, if we were to use the first one, Session events, and wanted to specify a start date of 9/1/24 and for user ‘pvl’ we would format it as follows:

http://99.99.99.99:8080/core/1.0/API/sessionEvents?startdate=2024-09-01&user=pvl

The parameters are optional; if you do not use them you get all events in that category on that server. Parameters allow for filtering the results to the information date range/user range that is desired for reporting.

This API can be filtered on a start date and/or an end date and on a specific username, if desired. Data is returned in html format if run in a browser and json if run in an automation program.

Run in a browser tab, with only a start date parameter, it will return information as follows.

If run from Postman or a similar program, it is sent as a GET call. There is no body, only the URL is needed to run this. The date returns in the results section.

With either option, this shows the TDO ID for the session, the user name, the IP address that was used for access, the date/time for login and logout, whether the session is still active (‘true’) or not (‘false’), and the duration the session was/is active for.

Note that startdate is an inclusive parameter (include sessions starting on this date) but end date is an exclusive parameter (only include sessions ending prior to this date).

This API returns information regarding business rules creation, updates, and deletions. It will include the user who made the changes, the IP address they logged in from, and the associated coverage set.

This API can be run in a browser tab or an automation program. The URL and results are shown below as run in Postman.

This API returns information on when a coverage matrix was run to calculate coverage based on entered business rules. It is run as a GET call.

The parameters available are the same options as for sessionEvents API. The results below are shown from Postman but can be run from a browser window or any automation program.

This API is also a GET call. It will return the same user and IP address information as the other reporting calls, and will show the project and data block name and version for any assembled data that has been retrieved (downloaded) from TDO.

This call is run as a GET. It uses the same three parameters as the other reporting API’s but uses two additional ones – projectname and projectversion. If these parameters are used, you must use both of them.

This call returns a data assembly summary, including how many rows were generated and how many rows had errors. If the ‘errors’ indicator is ‘[ ]’ then there were no errors detected during data assembly.

If there were errors, it includes information on the rows that contained errors and the number of errors per row.

This result is for the project ‘mug_test_project 1.0’ and returned no errors.

For a data assembly that included errors, the partial return information is shown below.

This assembly contained 12 rows with errors. The error message and resulting data for the first row are also shown (the full error report for this assembly contains the error message for each row in similar detail).