1 Introduction
2 Overview
3 Common Design Structure
4 Common Attribute Structure
5 Common Error Response Structure
6 Send Design
- 6.1 Request
- 6.2 Response
- 6.3 Valid Response
7 Get Design
- 7.1 Request
- 7.2 Response
  - 7.2.1 Valid Response
  - 7.2.2 Error Response
8 Update Design
- 8.1 Request
- 8.2 Response
  - 8.2.1 Valid Response
  - 8.2.2 Error Response
9 Create Design
- 9.1 Request
- 9.2 Response
  - 9.2.1 Valid Response
  - 9.2.2 Error Response

Introduction

This document will describe the technical aspects of CableBuilder’s ERP Integration API for ERP to be able to properly communicate with CableBuilder.

It will detail the expected request and response bodies of each request and how CableBuilder handles the responses and how ERP should handle responses from CableBuilder.

Overview

The CableBuilder ERP Integration API is a RESTful web service that sends and receives a JSON body of content.

While the API does not fully satisfy all RESTful standards, this is due to the nature of the functionality.

Where possible CableBuilder will return appropriate error codes for the ERP system to deal with.

Common Design Structure

All four requests will utilise this same JSON structure either as the request body, the response body or both.

Each request has minor variances in what can and should be included that will be expanded on in each specific request below.

{
    "detail": {
        "design": "EXAMPLE_DESIGN",
        "designAlternative": 0,
        …
    },
    "header": {
        "attributes": []
    },
    "plant": {
        "plant": "PLANT_A",
        "attributes": []
    },
    "operations": [{
            "operation": 10,
            "attributes": [],
            "resources": [{
                    "resource": 10,
                    "resourceName": "LAY_A_01",
                    "attributes": []
                }
            ],
            "layers": [{
                    "layer": 10,
                    "processName": "LAYUP",
                    "attributes": [],
                    "boms": [{
                            "position": 10,
                            "attributes": []
                        }
                    ]
                }
            ]
        }
    ]
}

The detail section contains additional information about the design that are either not
attributes, such as dates and users, or for ERP validation purposes.

{
    "design": "EXAMPLE_DESIGN",
    "designAlternative": 0,
    "version": 2,
    "level": 0,
    "order": 0,
    "createdBy": "admin",
    "createDateTime": "2020-10-05 12:23:11.0",
    "versionCreatedBy": "admin",
    "versionCreateDateTime": "2020-10-05 12:59:17.0",
    "lastUpdatedBy": "admin",
    "lastUpdateDateTime": "14-Oct-2020",
    "approved": false,
    "active": false,
    "inERP": true,
    "inDate": true,
    "validationFormulaResult": "",
    "valid": true,
    "errors": [],
}

Field	Type	Description
design	String	The design / item code.
designAlternative	Integer	The design’s alternative.
version	Integer	The version of the design alternative
level	Integer	The level of the design as a bom within a multi-level design.
order	Integer	The order in which the design appears as a bom within the same level of a multi-level design.
createdBy	String	The username who created version 0 of the design alternative.
createDateTime	String	The date and time version 0 of the design alternative was created.
versionCreatedBy	String	The username who created version of the design alternative.
versionCreateDateTime	String	The date and time that version of the design alternative was created.
lastUpdatedBy	String	The username who last changed the design alternative.
lastUpdateDateTime	String	The date and time that the last change to the design alternative was made.
approved	Boolean	Is the design approved.
active	Boolean	Is the design attribute “status” set to “Active”.
inERP	Boolean	Is the design already in ERP (uploaded column in version table = 2)
inDate	Boolean	Is the design in date (design attribute “outOfDate” = 0)
validationFormulaResult	String	The value of the validation formula execution.
valid	Boolean	Determined by CableBuilder configuration options that account for the previous 5 boolean fields.
errors	Array	If any errors are encountered, they are placed here. Any attribute related errors (e.g. Update Design request) will exist in each attribute’s “message” field and here in the errors array.

Common Attribute Structure

Each section contains an array of attributes. Not all fields in the object are necessary and will
be expanded upon in each specific request.

{
    "name": "cost",
    "description": "Cost",
    "type": "FLOAT",
    "uom": "£",
    "value": "3424.04",
    "success": null,
    "message": null
}

Field	Type	Description
name	String	The name of the attribute defined in CableBuilder
description	String	The description of the attribute.
type	String	The type of attribute, set in CableBuilder e.g. FLOAT, INTEGER, CHAR
uom	String	The attribute’s unit of measure.
value	String	The value in the design.
success	Boolean	True or false, for updates only.
message	String	Message for Update Design request. Possible messages: Success Attribute has no difference. Attribute is not present in the design. Attribute is a system attribute and cannot be updated.

Common Error Response Structure

When receiving a JSON body request or response CableBuilder will account for a specific error response object in the event of an error occurring on ERP side.

It is up to the ERPs side to ensure any unexpected requests are accounted for and transformed into the
appropriate structure.

CableBuilder does the same thing to account for and log any potentially bad requests assuming the request gets as far as the ERP API servlet.

{
    "status": 400,
    "error": "Bad Request",
    "message": "JsonException - DETAILED ERROR WITH STACK TRACE",
    "timestamp": "2020-11-09T12:59:26.109",
    "path": "http://ERP_REST_SERVER/sendDesignEndpoint"
}

Field	Type	Description
Field	Type	Description
status	Integer	HTTP Status code
error	String	HTTP Status code string
message	String	Detailed message of the error. May include stack trace information if the error was an internal server error 500.
timestamp	String	Time the response was received (formatted YYYY-MM-DDTHH:mm:ss:sss)

If CableBuilder is the one receiving the above error response, timestamp and path are not
actually used, but the body is stored in the transfer log table for future lookup, they can be
null or omitted.

Send Design

Method: POST
Sender: CableBuilder
URL: Defined by ERP endpoint

Request

Refer to the common design structure.

The various sections (“header” “plant”, “operation” etc.) of the structure are only included if
an attribute has been mapped. For example, if only a single BOM attribute is mapped then
an operation and layer will exist to house the bom. Removing the mapping will remove all
structures as nothing is mapped.

If the section is included, CableBuilder will always include the relevant information to that
section, such as plant name, layercode and processName, resource and resourceName,
and position for the bom for further identification.

Refer to the common attribute structure.

The attribute objects are populated with “name, “description”, “type”, “uom” and “value”
however no conversion is done as the values in both the database and JSON are all stored
as strings.

Response

CableBuilder expects one of two possible responses from ERP. Either the valid Send Design
response body structure shown below, or the common error response structure in the
previous section.

Valid Response

{
    "success": true,
    "errors": [],
    "update": null
}

Field	Type	Description
success	Boolean	True or false. ERP will tell CableBuilder if the process was successful or not.
errors	Array (can be null or omitted)	An optional array of optional messages regardless of success – e.g. provide an errors, warnings, notes etc.
update	Common design structure (can be null or omitted)	If an update to a design is required (regardless of success), the common design structure can be included here to update the design the same way the Update Design request would.

Get Design

Method: POST
Sender: ERP
URL: http://localhost:8080/live/rest/erpIntegration/getDesign

Request

The following request body is expected when requesting a design using the Get Design
CableBuilder endpoint.

{
    "design": "EXAMPLE_DESIGN",
    "designAlternative": 0,
    "singleLevel": true
}

Field	Type	Description
design	String	The design / item code.
designAlternative	Integer	The design alternative.
singleLevel	Boolean (can be null or omitted)	Optional – to only include the design requested.

Response

CableBuilder will respond with one of two response objects, either the valid response or the
common error response.

Valid Response

Refer to the common design structure.

The response to Get Design is an array of common design structures. If singleLevel is
omitted or false then the response body array will contain all designs and sub designs
recursively, ordered by level and order, both descending with no duplicates. The highest
level and order of a duplicate design will be used.

As with the Send Design logic, only sections with mapped attributes will be included. All
additional information such as plant, layercode, processName etc will also be included. The
design will also go though validation but not prevent anything from being returned to ERP – it
will be ERP’s responsibility to use these values to determine if it wants to continue or not.

Refer to the common attribute structure.

The attribute objects will be populated with “name”, “description”, “type”, “uom” and “value”.

Error Response

Refer to the common error response structure.

If an error occurs that CableBuilder cannot recover from within the limitations of the request (e.g. bad requests), the common error response will be returned. Below is a list of handled exceptions for the Get Design request.

Message	Code	Error	Description
RequestBodyNotDefinedException	400	Bad Request	No request body found.
JsonException	400	Bad Request	Problem with JSON formatting – e.g. unterminated string, unexpected field, unexpected value or missing required field.
DesignNotDefinedException	400	Bad Request	Design and/or design alternative are not properly defined in the request body.
DesignDoesNotExistException	404	Not Found	The requested design does not exist in CableBuilder.
Request Not Found	404	Not Found	The request URL does not exist. Examples included.
Method Not Allowed	405	Method Not Allowed	If the request is not a POST request.
Exception	500	Internal Server Error	An unhandled exception was caught.

Update Design

Method: POST
Sender: ERP
URL: http://localhost:8080/live/rest/erpIntegration/updateDesign

Request

Refer to the common design structure.

A request to Update Design requires the common design structure as the JSON request body. Only sections with attributes you wish to update need to be included.

Refer to the common attribute structure.

The only two fields required in this instance are “name” and “value”. You may include the others if you wish as the structure is common for all requests, but they are not validated or used.

Response

CableBuilder will respond with one of two response objects, either the valid response or the common error response.

Valid Response

Upon completing the Update Design request without encountering any fatal errors, the returned response body will be the same incoming request body common design structure but with the “success” and optionally “message” fields of each attribute populated.

If an attribute cannot be updated for any reason, its message is set as an error, but also added to the global “errors” array within the “details” structure. Success is set to true or false accordingly. See the common attribute structure for a list of possible message values. Warnings (yellow) and Success (green) are both treated as success.

Error Response

Refer to the common error response structure.

If an error occurs that CableBuilder cannot recover from within the limitations of the request (e.g. bad requests), the common error response will be returned. Below is a list of handled exceptions for the Update Design request.

Message	Code	Error	Description
RequestBodyNotDefinedException	400	Bad Request	No request body found.
JsonException	400	Bad Request	Problem with JSON formatting – e.g. unterminated string, unexpected field, unexpected value or missing required field.
DesignNotDefinedException	400	Bad Request	Design and/or design alternative are not properly defined in the request body.
OperationNotDefinedException	400	Bad Request	An operation, resource, layer or bom attribute was found but operation was not properly defined (must be 0 or more).
LayerNotDefinedException	400	Bad Request	A layer or bom attribute was found but the layercode was not properly defined (must be greater than 0).
ResourceNotDefinedException	400	Bad Request	A resource attribute was found but the resource number was not properly defined (must be greater than 0).
BomNotDefinedException	400	Bad Request	A BOM attribute was found but the bom position was not properly defined (must be greater than 0).
DesignDoesNotExistException	404	Not Found	The requested design does not exist in CableBuilder.
Request Not Found	404	Not Found	The request URL does not exist. Examples included.
Method Not Allowed	405	Method Not Allowed	If the request is not a POST request.
Exception	500	Internal Server Error	An unhandled exception was caught.

Create Design

Method: POST
Sender: ERP
URL: http://localhost:8080/live/rest/erpIntegration/createDesign

Request

Refer to the common design structure.

A Create Design request body will be the same common design structure used throughout this document.

The following attributes and fields are required for a successful creation.

Field	Type	Description
header.standard	Attribute	A design header attribute representing the desired standard is required.
plant.plant	String	A valid plant structure with a plant value is required to know which plant the design will be created in.
operation.operation	Integer	If an operation, resource, layer or BOM needs to be created, a value operation of 0 or more is required.
resource.resource	Integer	If a resource needs to be created, a valid resource greater than 0 is required.
resource.resourceName	String	If a resource needs to be created, a valid resource object is required.
layer.layercode	Integer	If a layer or BOM needs to be created, a valid layercode greater than 0 is required.
layer.processName	String	IF a layer needs to be created, a valid process object is required.
bom.position	Integer	If a BOM needs to be created, a valid position greater than 0 is required.
bom.BOMitem	Attribute	To create a BOM, two attributes representing BOMitem and BOMdesignAlternative are required.
bom.BOMdesignAlternative	Attribute

Response

CableBuilder will respond with one of two response objects, either the valid response or the common error response.

Valid Response

Upon completing a successful (valid) Create Design request, CableBuilder will return the same common design structure from the incoming request body, but populated.

Error Response

Refer to the common error response structure.

If an error occurs that CableBuilder cannot recover from within the limitations of the request (e.g. bad requests), the common error response will be returned. Below is a list of handled exceptions for the Create Design request.

Message	Code	Error	Description
RequestBodyNotDefinedException	400	Bad Request	No request body found.
JsonException	400	Bad Request	Problem with JSON formatting – e.g. unterminated string, unexpected field, unexpected value or missing required field.
DesignNotDefinedException	400	Bad Request	Design and/or design alternative are not properly defined in the request body.
PlantNotDefinedException	400	Bad Request	Either the plant object was not included or the plant field within the plant object was not properly defined.
PlantDoesNotExistException	500	Internal Server Error	The defined plant does not exist within the CableBuilder database.
StandardNotDefinedException	400	Bad Request	Either the header object was not included or the attribute “standard” was not properly defined.
StandardDoesNotExistException	500	Internal Server Error	The defined standard does not exist within the CableBuilder database.
OperationNotDefinedException	400	Bad Request	An operation, resource, layer or bom attribute was found but operation was not properly defined (must be 0 or more).
LayerNotDefinedException	400	Bad Request	A layer or bom attribute was found but the layercode was not properly defined (must be greater than 0).
ProcessTypeNotDefinedException	400	Bad Request	The processName field within the layer structure was not properly defined.
ProcessTypeDoesNotExistException	500	Internal Server Error	The defined process name does not exist within the CableBuilder database.
ResourceNotDefinedException	400	Bad Request	A resource attribute was found but the resource number was not properly defined (must be greater than 0).
ResourceTypeNotDefinedException	400	Bad Request	The resourceName field within the resource structure was not properly defined.
ResourceTypeDoesNotExistException	500	Internal Server Error	The defined resource name does not exist within the CableBuilder database.
BomNotDefinedException	400	Bad Request	A BOM attribute was found but the bom position was not properly defined (must be greater than 0).
BomDesignDoesNotExistException	400	Bad Request	Cannot find the design defined by BOMitem and BOMdesignAlternative within the CableBuilder database.
InvalidDesignCodeException	400	Bad Request	Invalid character found within the design code. List of available characters. The following characters are not accepted: \\ + & # % \" ' an empty space or multiple concurrent spaces.
DesignExistsException	409	Conflict	The design to create already exists within the CableBuilder database.
Request Not Found	404	Not Found	The request URL does not exist. Examples included.
Method Not Allowed	405	Method Not Allowed	If the request is not a POST request.
CreateDesignException	500	Internal Server Error	An unhandled exception was caught during the creation part of the request. If rollback is disabled, the design may be in a broken state.
Exception	500	Internal Server Error	An unhandled exception was caught.

CableBuilder Support

Technical Guide

Introduction

Overview

Common Design Structure

Common Attribute Structure

Common Error Response Structure

Send Design

Request

Response

Valid Response

Get Design

Request

Response

Valid Response

Error Response

Update Design

Request

Response

Valid Response

Error Response

Create Design

Request

Response

Valid Response

Error Response