Design Studio Composition Engine Application Programming Interfaces

API

1. Create New Composite Solution

Operation Name
createCompositeSolution
Trigger
This API is called when the user creates a new composite solution by clicking the + sign in the Design Studio.
Request
{
userId:string;//mandatory

}

Response
{
cid: string //serves as session Id.
success : boolean,
errorMessage: string // if generated by the Composition Engine

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must return the success as false if the userId is not provided and should return a user friendly error message such as – “User Id required”.
  3. The Composition Engine will create a new cdump file, which will be named and versioned later on when the save composite solution API is called. Initially the cdump file will not have any nodes or links populated in it. They will be added with each addNode and addLink operation called by the UI Layer, or modified with deleteNode, deleteLink, modify Node, modifyLink operations, described later.
  4. The Composition Engine will generate a UUID, which serves as a session Id, and populate the cid field in the cdump file with this UUID.
  5. The Composition Engine must associate the user Id with the cid.
  6. The Composition Engine will populate the ctime field with the current time stamp.
  7. The solution Id is not available to Composition Engine at this time. It will be available when the solution is stored in the backend catalog.
  8. Make the ProbeIndicator in the cdump file as “false”.
  9. Mark the validSolution flag in the cdump file as “false”.
  10. At this time the Composition Engine is not storing any data in the Catalog DB nor in the Nexus repository.
  11. The Composition engine must return the cid and success code to the caller.

2. Save Composite Solution - User clicks Disk Icon on Design Studio

Operation Name

saveCompositeSolution

This operation creates an entry for a new solution and its version or updates an entry for the existing solution version in Catalog DB and commits the solution (cdump file) to the Nexus repository.

Trigger

This operation is called when the user request the SAVE of the composite solution.

Request

{

userId: string,// user logged into Portal – mandatory

solutionName: string, //name provided by the user – mandatory – this can be changed at any time on SAVE operation

solutionVersion: string, //version provided by the user – mandatory – this can be changed at any time on SAVE operation

solutionId: String, //provided only if an existing solution is being updated, otherwise it will be empty.

description: string, //provided by user

cid: string // composition Id originally generated by backend and returned to UI Layer as a response to createNewCompositeSolution API, now it is provided as input by UI Layer – this field is mandatory if the solution Id is missing. Mandatory for initial save request.

ignoreLesserVersionConflictFlag: boolean //populated if the user wants to ignore overwriting of lesser version of this solution.

}

Response

{

Success: boolean, //

errorMessage: string // (for example – when the user attempts to over write a previous

cdump file of the composite solution// includes nodes & edges of graph

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that the mandatory parameters have been populated, otherwise it should return a user friendly message, such as “Solution Name missing”, “Solution Version missing”, etc.
  3. The Composition Engine must ensure that the cid provided in the input is one of the cid’s it had generated earlier, otherwise it should return an error message to the UI Layer – “Unknown Composition Id”.
  4. Mark the validSolution flag in the cdump file as “false”.
  5. (Future) The Composition Engine must call the Modeling Engine to ensure the TOSCA validation of cdump file. (Future Sprint actions)
  6. The Composition Engine will:
    1. CASE – 1: If this is a new solution (cid is provided and solutionId is missing)
      1. Create a new solution entry in the Catalog DB with the solution name and solution version provided as the input of the API. The Catalog DB will generate and provide the solutionId. The Composition Engine must make sure to set the following values as follows in the backend Catalog DB:
        1. isComposite is set to TRUE
        2. toolKitType = “DS”
        3. visibility level = PRIVATE
      2. Correlate the solution Id with the cid provided by the API.
      3. Store the validated cdump JSON file, so far built, in the Nexus – cdump file location.
      4. Update the cdump file location in the solution version table.
      5. Populate the solutionId field of the cdump file with the solutionId provided by the Catalog DB.
      6. Populate cname and version fields in cdump file with solution name and version provided in the API input.
      7. Populate the mtime field in the cdump file with the current timestamp.
    2. CASE – 2: If the solutionId already exists and the solution name and solution version provided (inputted) by the API also already exists (version conflict) in the Catalog, then:
      1. (Now there exists an updated cdump file in the Composition Engine)
      2. Composition Engine must now make an association between cid and solutionId.
      3. Populate the mtime field in the cdump file with the current timestamp.
      4. Composition Engine will now replace (and discard) the existing cdump file in Nexus repository with the updated (i.e., in memory) cdump file.
      5. Update the existing solution version entry to point to the location of the updated cdump file saved in the Nexus repository.
      6. Update the timestamp in the catalog DB.
    3. CASE – 3: : If the solutionId and the solution name already exists in the Catalog DB, but the solution version provided by API is different which does not exist in the Catalog DB, then
      1. (Now there exists an updated cdump file in the Composition Engine)
      2. The Composition Engine will create a new version of the Solution in the Catalog DB, against the version number that is provided in the API input.
      3. Populate cname and version fields in cdump file with solution name and version provided in the API input.
      4. Populate the mtime field in the cdump file with the current timestamp.
      5. The Composition Engine will save the in – memory cdump file in the Nexus.
      6. The Composition Engine will populate the cdump file location in the new Solution Version table, created in the step above.
      7. The Composition Engine will update the timestamp if the Catalog DB.
    4. CASE – 4: SolutionId, Solution Name and Solution Version already exists in the DB, but the solution version provided by the user is not the latest one (i.e., it is smaller than the most recent version) and the “ignoreLesserVersionConflictFlag” flag is set to False (default value).
      1. The Composition Engine will do a lookup operation as usual, and if it finds the solution version provided by the user already exists and it is smaller than the most recent version, it must set success flag as false and send error message to the UI Layer – “Do you want to update a previous version of this solution?”
      2. The UI Layer will present this message to the user.
      3. If the user accepts, then the UI Layer will send another saveCompositeSolution API call to the Composition Engine, this time with “ignoreLesserVersionConflictFlag” flag set to True.
    5. CASE – 5: Solution Id, Solution Name and Solution Version already exists in the DB, but the solution version provided by the user is not the latest one (i.e., it is smaller than the most recent version) and the “ignoreLesserVersionConflictFlag” flag is set to True.
      1. Populate the mtime field in the cdump file with the current timestamp.
      2. Composition Engine will now replace the existing cdump file in Nexus repository with the updated (i.e., in memory) cdump file.
      3. Update the existing solution version entry to point to the location of the updated cdump file saved in the Nexus repository.
  7. The Composition Engine will populate the following fields in the Catalog DB:
    1. userId (provided in the request)
    2. ownerId: Same as userId
    3. provider: The provider (Organization) should have been already provisioned in the USER TABLE - (check with Chris and Ashwin)
    4. toolKitType Code: “DS”
    5. category: (Check with Chris)
    6. description: provided in the input
    7. visibilityLevel: “PR”

3. Read complete Solution Graph from Nexus

Operation Name readCompositeSolution Trigger This operation is called when the user performs a double click operation on an existing composite solution in the Catalog Palette in order to display the complete solution in the Design Canvas.

Request

{

userId: string // mandatory

solutionId: string, // id of composite solution in catalog - mandatory

version: string //mandatory

}

Response

{

cdump: JSON, //JSON of cdump

errorMessage: string //optional

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must check if the solutionId and version are found in the Catalog DB, otherwise it should return a user friendly error message back in the response, such as “Requested Solution Not Found”.
  3. The Composition Engine must retrieve the location of the cdump file from the Catalog DB, via a query into Solution and Version Tables.
  4. The Composition Engine must retrieve the cdump file from the Nexus repository and return the JSONised string of the file to the client.

4. Delete Composite Solution

Operation Name

deleteCompositeSolution

Trigger

This operation is called by the UI Layer when the user requests the deletion of the composite solution.

Only the owner of the solution can request this operation, otherwise “Not authorized to perform this operation” is returned by the Composition Engine.

Request

{

solutionId: string, // id of composite solution in catalog - mandatory

version: string, //mandatory

userId: string ///mandatory

}

Response

{

success: boolean,

errorMessage: string //optional

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must check if the solutionId and version are found in the Catalog DB, otherwise it should return a user friendly error message back in the response, such as “Requested Solution Not Found”.
  3. The Composition Engine must check the Catalog DB if the userId provided is the owner of the composite solution – both the solutionId and Version, otherwise it should return the success flag as False and send a user friendly error message back in the response, such as “User not authorized to perform the operation”.
  4. If the user is the owner of the solution, then Composition Engine must perform the following functions:
    1. Delete the cdump file associated with the solution version from the Nexus.
    2. Delete the Version entry of the solution in the Catalog DB.

5. Add node

Operation Name

addNode

Trigger

This operation is called when the user drags and drops:

  1. A basic building block such as an ML Model, or a DataMapper, or a DataBroker, or a Collator, or a Splitter (generally referred to as node) from the Catalog Palette to the canvas.

Request

{

userId: string, // mandatory

solutionId: string // this field will be empty for a new un – saved solution. It is mandatory for a saved solution

version: string// this field will be empty for a new un – saved solution. It is mandatory for a saved solution

cid: string //this field should be populated (mandatory) if the solutionId and version is missing such as for a new un – saved solution.

nodeName: string,// optional – it may not be available initially, provided by the DS User

nodeId: string, // mandatory – generated by UI Layer

nodeSolutionId: string //mandatory – solution Id of the basic node in Common Catalog DB. This value is retrieved from fetchCatalogItems API

nodeVersion: string // mandatory – version of the basic node in Common Catalog DB. This value is retrieved from fetchCatalogItems API

proto_url: url of the proto file of the ML model or data broker or data mapper, //  change for all nodes – Data Broker or Data Mapper

type: {“name”: “DataMapper or MLModel or DataBroker”}, //  Change for Data Mapper or Data Broker

typeInfo: {}, // Type information - empty in this Sprint

properties: [ ], // JSON List of Node Properties.

requirements: [ // this field should be populated by UI Layer if a node has one or more requirements in the TGIF.json file. This is a list of requirements.

{

“name”:”“,

“relationship”:”“,

“id” : “”,

“capability” : {

“name” : “calls.request.format+calls.request.version+calls.response.format+calls.response.version For DM or DB populate Any,initially and when connected name of the output message”, Change for Data Mapper, Data Broker

“id” : “”

},

“target” : {

“name” : ” name-of-target-node-of-this-requirement-if-it-is-connected”, //otherwise empty

“description”: “”

},

“target_type” : “Node”

},

{

Another requirement spec.

}

], //end of requirements list

capabilities: [// this field should be populated by UI Layer if a node has one or more capabilities in the TGIF.json file. This is a list of capabilities.

{

“id” : “”,

“name” : “”,

“target” : {

“name” : “provides.request.format+provides.request.version+provides.response.format+provides.response.versionFor DM populate Any “,  Change for Data Mapper

“id” : “”

},

“target_type” : “Capability”,

“properties” : null

},

{

“id” : “”,

“name” : “”,

“target” : {

“name” : “provides.request.format+provides.request.version+provides.response.format+provides.response.version version For DM or DataBroker populate Any and connected one of the input message”,  Change for Data Mapper or Data Broker

“id” : “”

},

“target_type” : “Capability”,

“properties” : null

}

], //end of capabilities list

“ndata” : {// node’s position in the design canvas

“ntype” : “”,

“px” : 385.89287722216187, number

“py” : 380.5962040115248,  number

“radius” : 10,  number

“fixed” : boolean,

}

}//end – of – Request

Response

{

success: boolean,

errorMessage: string // error string to be displayed to DS User.

}

Behavior

  1. The Composition Engine must ensure that all the fields marked mandatory are populated and the request JSON structure is valid, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation - Node Name missing”, “Cannot perform requested operation - Node Id missing”, etc.
  2. The Composition Engine must make sure that the nodeId does not already exist in the cdump file, otherwise it must send success as false and an error message such as “Node Id already exists – cannot perform the requested operation”.
  3. The Composition Engine must create/add a child node entry under the “nodes” list of the cdump file.
  4. The Composition Engine must populate the node element in the cdump file as follows:
    1. name = node name provided by the API – this is inputted by the DS user
    2. id = node Id provided by the API – this is generated by the UI Layer
    3. solutionId = solution Id of the node provided by the API – this is the solution Id of the Node in the Common Catalog Database
    4. version = version of the node provided by the API – this is the solution version number of the Node in the Common Catalog Database
    5. proto_url = url of the proto file of the model or data broker or data mapper.
    6. type = {} – populate as provide by API. {“name”: “DataMapper or MLModel or DataBroker or Probe”},
    7. requirements = List of requirements as received by the API (see sample JSON file)
    8. capabilities = List of capabilities as received by the API (see sample JSON file)
    9. properties = [] – populate as empty list
    10. typeInfo = {} – populate as empty JSON object
    11. ndata = populate this JSON object with values received by the API.
  5. The Composition Engine need not save the cdump file in the Nexus repository.
  6. (Future – Validation Steps)

7. Delete Node

Operation Name

deleteNode

Trigger

This operation is requested when the user deletes a node in the composition graph. This node may be connected to other nodes or it may be an isolated (un-connected) one. When a node is deleted all links connected to it (either originate from it or terminate on it) must also be deleted. This operation may result in some existing nodes becoming isolated.

Request

{

userId: string, //mandatory

solutionId: string // this field will be empty for a new un – saved solution. It is mandatory for a saved solution

version: string// this field will be empty for a new un – saved solution. It is mandatory for a saved solution

cid: string // composition Id originally generated by backend and returned to UI Layer as a response to createNewCompositeSolution API, now it is provided as input by UI Layer – this field should be populated (mandatory) if the solutionId and version is missing such as for a new un – saved solution.

nodeId: string// mandatory

}

Response

{

success: boolean,

errorMessage: string // error string to be displayed to user.

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – Node Id missing”, etc.
  3. If the requested nodeId is not found in the cdump file, the Composition Engine must return success as false and a user friendly message, such as “Invalid Node Id – not found”.
  4. The Composition Engine must:
    1. Delete the specified node entry in the nodes list of the cdump file.
    2. Find all the links that are connected to the specified node (originate from the node or terminate on the node) and delete these link entries in the relations list of the cdump file.
    3. (Sprint - 4) For each link that terminates on the specified node, find the corresponding source node of the link. These source node are the ones whose Requirements are now un-fulfilled. These nodes may now need to display a warning message to the Design Studio user. (I think the UI Layer would automatically be able to display the warning message when a Requirement is un-fulfilled. Perhaps there is no need for the composition engine to send a warning message to be displayed on the affected nodes).
  5. Return success as True to the client.
  6. (NOTE: In future, composition engine may have rules to reject deletions)

9. Modify Node

Operation Name

modifyNode

Trigger

This operation is called by the UI Layer:

  1. When the user moves an existing node(ML Model, Data Mapper, Data Broker, Collator, Splitter) on the design canvas or
  2. When the user changes the name of the node in the design canvas, or
  3. When the user maps, i.e, connects an input field of the Data Mapper node to an output field of the Data Mapper node, or
  4. When the user deletes the existing mapping between a pair of input and output fields inside a Data Mapper, or
  5. When the user inputs a Script or local system data file path or target file url, or csv file field separator or first row (contains data or field names), or selects the data broker type or any of them by clicking the DONE button in the Pop UP UI associated with the S Port of the Data Broker, or
  6. When the user selects the field type of the source field name from the drop down list in the source table of the Data Broker, or
  7. When the user checks a field in the source table (then store field name, field type and checked box in cdump), or
  8. When the user maps, i.e., connects a source table field to the target table field of the Data Broker node via the drop down in the mapping area, or
  9. When the user deletes the existing mapping between a pair of source and target table fields inside a Data Broker, or
  10. When the user selects the collation scheme (Array based or Parameter based) followed by clicking the DONE button on the Pop Up UI associated with the Collation Selection Port (or URL) of the Collator, or
  11. When the user maps, the source parameter to the target parameter by selecting a drop down (tag number) value in mapping area of the Parameter – based Collator (not applicable for array based collation) and clicks the DONE button on Mapping Table, or
  12. When the user deletes the existing mapping between a pair of source and target parameters by removing a selected value to an empty value in the mapping area of the Parameter – based Collator and clicks the DONE button. (not applicable for array based collation).

Request

{

userId: string // mandatory

solutionId: string // this field will be empty for a new un – saved solution. It is mandatory for a saved solution

version: string// this field will be empty for a new un – saved solution. It is mandatory for a saved solution

cid: string //this field should be populated (mandatory) if the solutionId and version is missing such as for a new un – saved solution.

nodeId: string, // mandatory

nodeName: string // populated if a new name is assigned to the node (Model, Data Mapper, Data Broker, Collator), otherwise empty.

ndata: {

ntype: string // populated as “” in this Sprint

px: number,

py: number

}//either nodeName or ndata field or field_map should or data_broker_script should be populated be populated

field_map: {  Change for Data Mapper

map_action: “add or delete”

input_field_message_name: string,

input_field_tag_id: string,

output_field_message_name: string

output_field_tag_id: string

}//either nodeName or ndata field or field_map or data_broker_map or data_broker_script should be populated

data_broker_map: {  Change for Data Broker – Note complete mappings need to be saved, along with their source and target fields. However, the source and target tables are auto generated in the UI based on the script and output protobuf message of Data Broker.

“map_action”: “add or delete or update” //NOTE “add” and “delete” actions are always associated with a pair of source and target field mappings The mappings need to be added or deleted in the mapped_to_field. If it is “update” then cdump file needs to be updated with the corresponding field values (4/4/2018: this field will be empty because of the revised mapping table in UI)

“data_broker_type”: “CSV_File or JSON_File or Image_File or SQL_Database”,

“map_inputs”: [

{

“input_field”: {

“name”: “name of source field”,

“type”: “string or int or float or boolean or Long or Double, Byte”,

“checked”: “YES or empty means NO”,

“mapped_to_field”: “tag number of the field in the target table, such as 1.2 or 2.3.4 or empty if it is not yet mapped”

}

}

],

“map_outputs”: [

{

“output_field”: {

“tag”: “1.1 or 1.2 or 4.3.2 etc.”,

“name”: “name of target field sepal_len”,

“type_and_role_hierarchy_list”: [

{

“name”: “string”,

“role” : “null”

},

{

“name”: “DataFrameRow”,

“role”: “repeated”

},

{

“name”: “DataFrame”,

“role”: “null”

}

]

}

}

],

“script”: “user provided multi line SQL or File system commands to read, parse and retrieve data from file or directory”,

“target_system_url”: “File or JDBC url in the target system”,

“local_system_data_file_path”: “CSV or JSON Sample Data File path on users local machine”,

“first_row”: “contains_data or contains_field_names. this field is only populated for CSV file Data Broker”,

“csv_file_field_separator”: “”, or ; or | , etc. characters”,

“database_name”: “as entered by user in Design Studio”,

“jdbc_driver_data_source_class_name”: “name provided by the user in DS”,

“table_name”: “extracted by DS from the Create Table Script”,

“user_id”: “user Id for JDBC access or the File Host for SSH access”,

“password”: “password for above user Id”

},

“collator_map”: {

“collator_type”: “Array-based or Parameter-based - For Array based map_inputs and map_outputs are not populated”,

“output_message_signature”: “json representation of output message signature - required for parameter based collation”,

“map_inputs”: [

{

“input_field”: {

“source_name”: “name of model that provides message to collator input port”,

“parameter_name”: “parameter name in Source Protobuf file. A source may provide multiple parameters for parameter based collation”,

“parameter_type”: “name of parameter type aka message signature in Source Protobuf file”,

“parameter_tag”: “parameter tag number in Source Protobuf file”,

“mapped_to_field”: “tag number of the field in the target message side, empty if it is not yet mapped”,

“error_indicator”: “True or False”

}

}

],

“map_outputs”: [

{

“output_field”:{

“Parameter_tag”: “tag number of the field in the target message side”,

“parameter_name”: “parameter name in Target Protobuf file”,

“parameter_type”: “name of parameter type aka message signature in Target Protobuf file”,

“parameter_rule”: “Required or Optional”

}

}

]

}

}

Response

{

success: boolean,

errorMessage: string // error string to be displayed to user.

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – Node Id missing”, etc.
  3. If the requested nodeId is not found in the cdump file, the Composition Engine must return success as false and a user friendly message, such as “Invalid Node Id – not found”.
  4. The Composition Engine must update the nodeName, ntype, px and py elements of the specified nodeId in the cdump file with the values provided.
  5. For a Data Mapper node, the Composition Engine must perform the requested map_action (add or delete) by appropriately updating the data_map in the properties section of the node in the cdump file.
  6. The Composition Engine need not save the cdump file in the Nexus repository.
  7. Return success as True to the client.
  8. (In future, engine may have rules to reject modifications).

11. Fetch Basic Building Blocks for a User

Operation Name

fetchCatalogItems

Trigger

This operation is called by the UI Layer when the user initially logs into the Design Studio in order to populate the Palette of catalog items to be displayed to the user based on his credentials. Both the simple solutions and composite solutions are retrieved. Only the following catalog items can be populated in the Palette for a given user:

  1. Catalog items marked “Public”
  2. Catalog items marked “Private” to the user.
  3. Catalog items marked as belonging to the user’s “Organization” of which the user is a member.

Request

{

userId: String // mandatory

}

Response

{

items: [list of catalog items

{

solutionId: string,

version : string,

ownerId : string,

solutionName: string,

description: string,

created: date as string,

modified: date as string

visibilityLevel: “private”, “organization”, “public”,

provider: string,

toolKit: string,

category: string,

icon: string // url or other resource id to display as icon in palette

},

{

Another catalog item

}

]//end item list

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – User Id missing”, etc.
  3. If the requested userId is not found in the catalog DB, the Composition Engine must return success as false and a user friendly message, such as “User Id – not found”.
  4. Composition engine will call the catalog database to retrieve all the existing solutions (both basic solutions as well as composite solutions) corresponding to the userId.
  5. If the requested userId is found in the catalog DB but there are no catalog items (either Private, or Organization, or Public) corresponding to the user Id, the Composition Engine must return success as true and an empty catalog item list to the client
  6. The Composition Engine must return a list of all catalog items which are:
  1. Marked “Public”.
  2. Marked “Private” to the user.
  3. Marked as belonging to the user’s “Organization” of which the user is a member.
  1. For each catalog item which meets the above criterion, the Composition Engine must retrieve the attributes specified in the response and return them to the client. The success parameter must be set to true.

12. Fetch Composite Solutions for a User

Operation Name

getCompositeSolutions

Trigger

This operation is called by the UI Layer when the user initially logs into the Design Studio in order to populate the List of Composite Solutions to be displayed to the user based on his credentials. Based on input parameter “visibilityLevel” this operation retrieves the Composite Solutions. User can pass either one, two or all the below option as value for the input parameter “visibilityLevel”, in order to retrieve the required list of Composite Solutions:

  1. “PR”: to include the private Composite Solutions in the list
  2. “OR”: include the organization level visible Composite Solutions.
  3. “PB”: to include the public level Composite Solutions.

Request

{

userId: string,// user logged into Portal – mandatory,

visibilityLevel : string // PR,OR,PB – mandatory. You can specify multiple value separated by ‘,’.

}

Response

{

items: [list of catalog items

{

solutionId: string,

version : string,

ownerId : string,

solutionName: string,

description: string,

created: date as string,

modified: date as string

visibilityLevel: “private”, “organization”, “public”,

provider: string,

toolKit: string,

category: string,

icon: string // url or other resource id to display as icon in palette

},

{

Another Composite Solution

}

]//end item list

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – User Id missing”, etc.
  3. If the requested userId is not found in the catalog DB, the Composition Engine must return success as false and a user friendly message, such as “User Id – not found”.
  4. Composition engine will call the catalog database to retrieve all the existing Composite solutions corresponding to the userId.
  5. If the requested userId is found in the catalog DB but there are no Composite Solutions (either Private, or Organization, or Public) corresponding to the user Id, the Composition Engine must return success as true and an empty catalog item list to the client
  6. The Composition Engine must return a list of Composite Solutions depending on the value(s) of input parameter “visibilityLevel”.

13. Clear canvas of Composite Solution

Operation Name

clearCompositeSolution

Trigger

This operation is requested when the user clicks “Clear” button to clear the contents of the canvas. This operation should delete all the nodes and links from the CDUMP file.

Request

{

userId: string, //mandatory

solutionId: string // this field will be empty for a new un – saved solution. It is mandatory for a saved solution

version: string// this field will be empty for a new un – saved solution. It is mandatory for a saved solution

cid: string // composition Id originally generated by backend and returned to UI Layer as a response to createNewCompositeSolution API, now it is provided as input by UI Layer – this field should be populated (mandatory) if the solutionId and version is missing such as for a new un – saved solution.

}

Response

{

success: boolean,

errorMessage: string // error string to be displayed to user.

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – Node Id missing”, etc.
  3. The Composition Engine must:
    1. Delete all the link entry in the nodes list of the cdump file.
    2. Delete all the node entry in the nodes list of the cdump file.
  4. Return success as True to the client.

14. Fetch TOSCA JSON of Basic Solution

Operation Name

fetchToscaJSON

Trigger

This operation is called by the UI Layer immediately after user has logged in and all the catalog items for the user have been populated in the Palette, via the fetchCatalogItems API.

For each item in the Palette, the UI Layer calls this operation to retrieve the JSON TOSCA file, i.e., the TGIF.json associated with the basic solution. Note that there is no TGIF.json file associated with the composite solution. TGIF.json only needs to be associated with the basic solutions (nodes).

Request

{

userId: string // mandatory

solutionId: string, // mandatory - global id of basic solution in catalog

version: string // mandatory

}

Response

{

JSON representation of TGIF.json file for the requested solution

success: boolean,

errorMessage: string // error string to be displayed to user.

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – Solution Id (or Version) missing”, etc.
  3. If the requested solutionId is not found in the catalog DB, the Composition Engine must return success as false and a user friendly message, such as “Incorrect Solution Id – not found”, or “Incorrect Version – not found”.
  4. For the requested solution Id and version, the Composition Engine must retrieve the location of the TGIF.json from the Catalog DB.
  5. The Composition Engine must retrieve the TGIF.json from Nexus at the location pointed out by Catalog DB
  6. The Composition Engine must return the json string of the TGIF.json file to the client, success set to true.

15. Fetch Protobuf JSON of Basic Solution

Operation Name

fetchProtobufJSON

Trigger

This operation should be called, for each node, when:

  1. A node is dragged from the catalog palette to the design canvas, or
  2. A composite solution is dragged from the catalog palette to the design canvas.

Note that each node, aka, the basic ML Solution (identified by the combination of solutionId and version), in a composite solution is associated with the following files:

  1. Protobuf file
  2. Protobuf.json file
  3. TGIF.json file

Output: This operation returns the JSON representation of all the operations specified in the Protobuf File, i.e, the serialized Protobuf.json

For each operation in the Protobuf.json file, this API should return the

  1. Operation name
  2. Input Message name(s)
  3. Output Message name(s)
  4. Detailed schema of each input message – as defined in the original Protobuf file. Each schema should be associated with the corresponding message name
  5. Detailed schema of each output message – as defined in the original Protobuf file. Each schema should be associated with the corresponding message name.

Request

{

userId: string //mandatory

solutionId: string // mandatory – solution Id of the basic node – this id is available from a previous fetchCatalogItems API call

Version: string // mandatory – version if the basic node - this value is available from a previous fetchCatalogItems API call

}

Response

{

protobuf_json: // JSON representation of Protobuf file.

success: boolean,

errorMessage: string // error string to be displayed to user.

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – Node Id missing”, etc.
  3. Identify the Protobuf.json file associated with the node type.
  4. For each operation in the Protobuf.json file, the Composition Engine must retrieve the
    1. Operation name
    2. Input Message name(s)
    3. Output Message name(s)
    4. Detailed schema of each input message – as defined in the original Protobuf file. Each schema should be associated with the corresponding message name
    5. Detailed schema of each output message – as defined in the original Protobuf file. Each schema should be associated with the corresponding message name.
  5. The Composition Engine must return the serialized representation of Protobuf.json file.

16. Close Composite Solution

Operation Name

closeCompositeSolution

Trigger

This operation is called when the user requests the closing of the composite solution currently open in the design canvas. This operation should be called when the user clicks the “X” mark on the top right hand corner of the canvas.

If there are unsaved changes when the user clicks “X”, then the user should be prompted to save the solution first.

  1. User chooses to save the solution: Call the saveCompositeSolution API and when its response is received by the UI Layer, then call the closeCompositeSolution API on the Composition Engine.
  2. User declines to save the solution: Any unsaved changes will not be saved to Nexus, but the cdump file will be closed (deleted). Call the closeCompositeSolution API.

Request

{

userId: string, //mandatory

solutionId: string // this field will be empty for a new un – saved solution. It is mandatory for a saved solution

version: string// this field will be empty for a new un – saved solution. It is mandatory for a saved solution

cid: string // composition Id originally generated by backend and returned to UI Layer as a response to createNewCompositeSolution API, now it is provided as input by UI Layer – this field should be populated (mandatory) if the solutionId and version is missing such as for a new un – saved solution.

}

Response

{

success: boolean,

errorMessage: string // error string to be displayed to user.

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – User Id missing”, etc.
  3. The Composition Engine must close the cdump file, without saving it in Nexus repository. The cdump that existed in the Nexus at the last SAVE operation will serve as the latest cdump when the user wants to read the composite solution later on).

17. On Hover Input Port

Operation Name

onHoverInputPort – This operation is not handled by the Composition Engine.

Trigger

This operation is called when the user hovers the mouse over the input port of the node.

Request

{

solutionId: string // mandatory – solution Id of the basic node – this id is available from a previous fetchCatalogItems API call

Version: string // mandatory – version if the basic node - this value is available from a previous fetchCatalogItems API call

operationName: string// mandatory – each input port is identified by the name of the operation

}

Response

Behavior

  1. The UI Layer should retrieve a list of one or more input message names associated with the given operation name from the JSON object representation of Protobuf already associated with the node. Note that this JSON object is already associated with the node when the node was dragged inside the canvas (or when the composite solution containing this node was dragged into the canvas).
  2. The UI Layer should display a pop up.
  3. The UI Layer should display the name of the operation and a list of one or more input message names inside the pop up. The message names should enclosed inside brackets – such as fit(DataFrame1, DataFrame2).
  4. The message names should be a hyperlink into the corresponding message schema – as defined in the original Protobuf file.

18. On Hover Output Port

Operation Name

onHoverOutputPort

Trigger

This operation is called when the user hovers the mouse over the output port of the node.

Request

solutionId: string // mandatory – solution Id of the basic node – this id is available from a previous fetchCatalogItems API call

Version: string // mandatory – version if the basic node - this value is available from a previous fetchCatalogItems API call

operationName: string// mandatory – each output port is identified by the name of the operation

Response

Behavior

  1. The UI Layer should retrieve a list of one or more output message names associated with the given operation name from the JSON object representation of Protobuf already associated with the node. Note that this JSON object is already associated with the node when the node was dragged inside the canvas (or when the composite solution containing this node was dragged into the canvas).
  2. The UI Layer should display a pop up.
  3. The UI Layer should display the name of the operation and a list of one or more output message names inside the pop up. The message names should enclosed inside brackets – such as fit(Prediction).
  4. The message names should be a hyperlink into the corresponding message schema – as defined in the original Protobuf file.

19. On Click of Message (Input or Output)

Operation Name

onClickMessage

Trigger

This operation is called when the user clicks on an input or an output message in the input/output port of the node.

Request

{

operationName: string //// mandatory – each input port is associated with an operation

messageName: string// mandatory – each operation name has input and output message(s)

}

Response

Behavior

  1. The UI Layer should retrieve the message schema of the named message from the JSON Object representation associated with the node.
  2. The UI Layer should convert the JSON representation of the message into its original Protobuf message schema format.
  3. The UI Layer should send the Protobuf message schema format to the Properties box.
  4. The Properties Box should display the message schema in the original Protobuf format.

20. Get Matching Models for a Port

Operation Name

getMatchingModels

Trigger

This operation is called by the UI Layer when the user clicks on the port of a node in the design canvas, in order to get a list of ML Models (i.e., basic building blocks) that match the message signature of the port.

The requirement is to enable the DS user to drag and drop the matching models from the “Matching Models” pane into the design canvas.

Request

{

userId: string // mandatory

solutionId: string // this field will be empty for a new un – saved solution. It is mandatory for a saved solution

version: string// this field will be empty for a new un – saved solution. It is mandatory for a saved solution

cid: string //this field should be populated (mandatory) if the solutionId and version is missing such as for a new un – saved solution.

port_data: {

port_type: “provider” or “consumer”/ Provider and Consumer ports are associated with the Input (unfilled circle) and Output (filled in circle) of an Operation

protbuf_data: [] //Array of JSON representation of one or more messages inside the Port

}//mandatory

}

Response

{

success: boolean,

matchingModels: [

{

name: String// name of the matching ML Model,

tgifReference: String //location of TGIF file in Nexus

}

] // list of the names of matching ML Models, i.e., basic building blocks,

errorMessage: string // error string to be displayed to user.

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – User Id missing”, etc.
  3. The Composition Engine must:
    1. Identify if the request is to find the matching models of a “Provider” port or a “Consumer” port.
    2. Retrieve the TGIF.json files of ML Models – the basic building blocks in the CCD, one after another.
    3. For a consumer port, search and match requested message signature with the message signatures on the Provider port(s) of the TGIF.json file, and if there is a match found, then populate the name of the ML Model and the TGIF.json reference of the Model in the matchingModels list (see Response section).
    4. For a provider port, search and match requested message signature with the message signatures on the Consumer port(s) of the TGIF.json file, and if there is a match found, then populate the name of the ML Model and the TGIF.json reference of the Model in the matchingModels list (see Response section)
    5. If no matches are found, then return success as false, and populate the errorMessage as “No matching models found”, otherwise return success as True.
  4. Return the response to the UI Layer.

21. Validate Composite Solution

Operation Name

validateCompositeSolution

Trigger

This operation is called by the UI Layer when the user clicks on the Validate Button in the Design Studio.

When the response to this API is received, the UI Layer, should populate the Validation Console with either a single success message or a list of error and warning messages returned by the backend Composition Engine.

Request

{

userId: string, //mandatory

solutionId: string // this field will be empty for a new un – saved solution. It is mandatory for a saved solution

version: string// this field will be empty for a new un – saved solution. It is mandatory for a saved solution

cid: string // composition Id originally generated by backend and returned to UI Layer as a response to createNewCompositeSolution API, now it is provided as input by UI Layer – this field should be populated (mandatory) if the solutionId and version is missing such as for a new un – saved solution.

}

Response

{

success: boolean,

validationMessages[]: string // A single “Validation Successful” message or a list of one or more Error messages and Warning Messages.

errorMessage: string // error string to be displayed to user.

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.
  2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – User Id missing”, etc.
  3. The Composition Engine must perform hte following validations:
    1. A composite solution can only have nodes of the following types.
      1. MLModel
      2. Splitter
      3. Collator
      4. DataBroker
      5. DataMapper
    2. A composite solution can have a single isolated (i.e., an unconnected) model of type “MLModel”.
    3. An isolated model of any type other than of type “MLModel” is not allowed in a composite solution.
    4. A composite solution cannot have more than one isolated (or unconnected) models, irrespective of their type.
    5. A composite solution with a combination of connected and isolated models is not a valid solution.
    6. Must retrieve the cdump file associated with the solution from Nexus repository.
    7. Perform validation of the cdump file to make sure that no model (basic building blocks) is isolated / unconnected.
    8. If there are isolated models in the composite solution, then for each such model, the composition engine must create an error message such as “Error – Mode Name is not connected.”
    9. An output port of a node can be connected to the input port of another node only if there exist matching message signatures on the pair of ports. (Rule checked by UI Layer)
    10. An output port of a node of type “MLModel” can be connected to ONLY one input port of another node of type “MLModel” or “DataMapper” or “Splitter” or “Collator”, [NOTE: Design Studio will NOT restrict the user, but during Validation this should be flagged as error.]
    11. An output port of a node of type “DataBroker” can be connected to ONLY one input port of another node of type “MLModel” or “DataMapper” or “Splitter” or “Collator”, [NOTE: Design Studio will NOT restrict the user, but during Validation we will flag this error.]
    12. An input port of a node of type “MLModel” can be connected to ONLY one output port of another node of any type. [NOTE: Design Studio will NOT restrict the user, but during Validation we will flag this error.]
    13. A node of type “DataBroker” cannot have its input port connected to any other node. (to be modified later)
    14. The Composition Engine must set success as False and send a list of error messages in the “validationMessages” list to the client.
    15. If there are no errors, the Composition Engine must:
      1. Create the Blueprint.json file (as described)
      2. Store the Blueprint.json in Nexus
      3. Store the location of Blueprint.json in Common Catalog DB.
      4. Set success as True and send “Successful” message in the “validationMessages” list to the client.
      5. Mark the validSolution flag in the cdump file as “true”.
      6. Store the cdump file in Nexus.
  4. If a Data Broker is included in the composite solution, then after the solution is successfully validated in the Design Studio, the Composition Engine must do the following functions:
    1. Retrieve the Protobuf file of the ML Model connected to the Data Broker from Nexus and populate it in the protobufFile field of the data_broker_map.
  5. If a Data Mapper is included in the composite solution, then after the solution is successfully validated in the Design Studio, the Composition Engine must do the following functions:
    1. Generate the Protobuf Wrapper for the Data Mapper – This Wrapper converts:
      1. From Java to Protobuf types for the outgoing message (on the output side of the Data Mapper).
      2. From Protobuf to Java types for the incoming message (on the input side of the Data Mapper)
    2. Create the jar file of the Data Mapper with the field level mappings, as designed in the Design Studio.
    3. Convert the jar to Microservices. Note the Data Mapper exposes an operation called mapData and the input arguments to the operation are the same as those defined on the input side of the Data Mapper.
    4. Create the Docker Image of the Data Mapper Microservice.
    5. Store the Docker image of the Data Mapper in the Nexus repository.
    6. Store the location of the docker image in the TGIF.json of the Data Mapper.

22. SetProbeIndicator

Operation Name

setProbeIndicator

Trigger

This operation is called by the UI Layer when the user clicks or un clicks the Probe Indicator Button in the Design Studio, to indicate if he wants the Probe to be included or not in the composite solution. By clicking this button the user intends to set or unset a probe indicator in the backend.

Request

{

userId: string, //mandatory

solutionId: string // this field will be empty for a new un – saved solution. It is mandatory for a saved solution

vetrsion: string// this field will be empty for a new un – saved solution. It is mandatory for a saved solution

cid: string // composition Id originally generated by backend and returned to UI Layer as a response to createNewCompositeSolution API, now it is provided as input by UI Layer – this field should be populated (mandatory) if the solutionId and version is missing such as for a new un – saved solution.

probeIndicator: String //True or False //Mandatory.

}

Response

{

success: boolean,

errorMessage: string //error string to be displayed to DS User.

}

Behavior

  1. The Composition Engine must check if the request JSON structure is valid, otherwise it should return success as false and a user friendly message, such as “Incorrectly formatted input – Invalid JSON”.

2. The Composition Engine must ensure that all the fields marked mandatory are populated, otherwise it must return success as “false” and populate the helpful error message which is displayed to the user, such as “Cannot perform requested operation – User Id missing”, etc.

  1. The Composition Engine must:
    1. Must set the probeIndicator to either “true” or “false” value in the cdump file as received in the request.

Including a Swagger File

Acumos uses Swagger to generate dynamic API docs. However, to read the docs you must have access to the Swagger server running on your Acumos instance. This can be inconvenient, so the Docs project uses a Sphinx plugin called sphinx-swaggerdoc, which provides an RST directive to render a swagger.json file. The sphinx-swaggerdoc extension is defined in the Documentation project’s conf.py file.

You an include your API JSON file either by pointing to a URL or by pointing to a file. This example uses a local file called example-swagger.json. See the sphinx-swaggerdoc for more examples.

.. swaggerv2doc:: example-swagger.json