CWork API Documentation (v1.4)

API Endpoint

CWork has a REST api that you can request to obtain data about your DNC or MDC installation.

Licensing

In order to fully or partially access CWork’s API, you need to have an according license. If you don’t or if you just don’t know, contact your reseller.
This documentation will tell you which licence you should acquire to access each ressources. Search for the Licence required property.

Here are the existing API licence types :

  • monitor

  • dnc
    More to come…

In the following documentation, any means that any API licence module will give you access to the specified function.

Authentication

As from v1.2 CWork’s API requires HTTP Basic Authentication (see RFC-2617 for more information on HTTP Authentication standards).

  • The user field of the Authorization header will need to be the API key corresponding to the desired CWork user.

  • The password field of the Authorization header shall be ignored.

To obtain the API Key corresponding to the CWork user please go to the user management panel (Tools > Preferences > ‘User and groups management’), double click on the desired user and copy the content of the API Key field.

HTTPS

As from v1.2 CWork’s API can work either over HTTP or HTTPS. Note that it cannot work on both protocol simultaneously. Default will be HTTPS.

In this case the only purpose of using HTTPS is communication encryption so self-signed certificates are used. Make sure to disable cerificate verification on your client.

To diable HTTPS please go to CWork’s engine preferences panel (Tools > Preferences > ‘Communication Services’), uncheck the HTTPS checkbox and apply changes. You will need to restart smmCApi.

API versionning

You can specify witch API you want to query by adding the version identifier in the HTTP Accept Header. Here is an example :

Accept: application/json+v1

Here is the matrix of CWork’s version and API version availability.

CWork version Embedded API version
<8.24 none
8.24 v1.0
8.24.1 v1.1
8.25 v1.2
8.25.1 v1.3
9.0 v1.4

Pagination

To avoid returning too big responses, some resources of this API include URI parameters-based pagination. Example : Documents list

The limit parameter will allow you to indicate the maximum item count you want in the resource list. If you omit this parameter, a default value will be used based on the resource. NB : the limit value will be capped to a fixed value based on the resource.

The page parameter will allow you to specify which page of items you want to get. Example : if you set limit to 100 and page to 3 you will get items from 200 to 299.

Error codes

CWork uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an internal error with CWork server.
Additionally, we will prodive you an Error code and a human-readable message providing more details about the error.

Here is the list of the currently existing errors :

Error code Message
1001 Function is not Allowed
1002 Version %s is not available
1003 No version selected. Please request a specific version
1004 Bad Request
1005 Paramaters must be a handle
1006 A function name is required
1007 A handle is required for this function.
1008 Method Not Allowed.
1009 Missing required parameter
1010 Error in parameters
2001 No JPG image is associated with this station [Obsolete after V1.3 if no image available we transmit a default image]
2002 No PNG image is associated with this station [Obsolete after V1.3 if no image available we transmit a default image]
2003 This station is not available or does not exist
2004 Ressource not found.
2005 This state does not exist
2006 This state is archived
2007 This station is not in MDC mode
2008 There is no document found with this ID
2009 There is no version found with this document ID
2010 Required fields have been omitted in your POST request body
2011 The Reference field for a document cannot be empty
2012 Document already exists
2013 There is no version found with this version ID
2014 The version identified by the verid provided does not belong to the document identified by the provided docid
2015 The specified file has not been found in the exchange folder
2016 An internal error occured while submitting the version
2017 The provided MD5 differs from the server-side processed MD5 hash. There might be an issue with the file integrity
3001 No license activate
4000 Unexpected Error

About data types

This section will describe all you have to know about the data formats we use and how to interpret them. We will try to be as consistent and predictible as possible regarding the use of these data types.

Strings

All strings within CWork’s API are UTF-8 encoded.

Dates & times

All dates within this API will be provided as ISO8601 format inculuding all date time and time zone designators. Here is an example :

2015-06-30T17:19:00.000+02:00

This example show the date format for June the 30th, 2015 at 5:19 PM in GMT+2 time zone.

Durations

All duration within this API will be provided in seconds.

Colors

All colors within this API will be described in hexadecimal (HEX) format. Here are a few examples of common colors

Color Hex code
Blue #0000FF
Red #FF0000
Yellow #FFFF00
White #FFFFFF
Black #000000
Green #00FF00

Files

All files transmited via the API (inbound or outbound) will be exchanged in a common folder in CWork’s working directory under /Temp/API-io/. CApi will automatically create this folder at startup if it doesn’t exists.

For example, when making a GET request to the version endpoint with the include_file parameter set to true, the system will copy the desired file in /Temp/API-io/ and retrieve the temporal name in the JSON response body along with the MD5 hash of the file. The client application will then be able to get it from here and check it’s integrity.

It’s the client application responsibility to delete the file in /Temps/API-io/ when it’s no longer used. If it’s not, then the system will delete it after 10 minutes.

Station

Ressources related to CWork’s stations (Also known as ‘CNC’).

Station

GET /stations/station_id
Responses200
Headers
Content-Type: application/json
Body
{
  "Handle": 7,
  "Name": "HSC70",
  "Description": "",
  "Disabled": false,
  "DNCMode": true,
  "MDCMode": true,
  "Workshop": "Building A",
  "DNCgroup": "HSCGroup",
  "MDCGroups": [
    "Milling",
    "Line4"
  ]
}

View a station detail
GET/stations/{station_id}

Available from : v1.0

Licence required : any

A station object has the following attributes:

Attribute name Description
Handle Unique identifier. Also known as ‘station_id’
Name The name of the station
Description The description of the station
Disabled Wether or not the station has been disabled.
DNCMode Wether or not the DNC mode has been enabled on the station.
MDCMode Wether or not the MDC mode has been enabled on the station.
Workshop Name of the virtual CWork workshop where the station is.
DNCGroup Name of the DNC group the station belongs to.
MDCGroups An array of the MDC groups the station belongs to.
URI Parameters
HideShow
station_id
number (required) Example: 7

ID of the station


Station

GET /stations/station_id/hasimg
Responses200
Headers
Content-Type: application/json
Body
{
  "Hasimage": true
}

Check if a image is linked to the station
GET/stations/{station_id}/hasimg

Available from : v1.4

Licence required : any

The response attribute is:

Attribute name | Description

Hasimage Wether or not the station has a image linked.
URI Parameters
HideShow
station_id
number (required) Example: 7

ID of the station


Station images

Retrieve the station’s image as a JPG or PNG file stream.

GET /stations/station_id/img?json=false
Responses200200
Headers
Content-Type: image/jpeg
Body
<JPG File>
Headers
Content-Type: image/png
Body
<PNG File>

Get station picture as jpg or png
GET/stations/{station_id}/img?json=false

Available from : v1.4 *If no image is linked to the station a default image is transmit *Maximum size is 350px * 350px

Licence required : any

URI Parameters
HideShow
station_id
number (required) Example: 7

ID of the station


Station list

GET /stations
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "Handle": 7,
    "Name": "HSC70",
    "Description": "",
    "Disabled": false,
    "DNCMode": true,
    "MDCMode": true,
    "Workshop": "Building A",
    "DNCgroup": "HSCGroup",
    "MDCGroups": [
      "Milling",
      "Line4"
    ]
  },
  {
    "Handle": 8,
    "Name": "DMU50",
    "Description": "",
    "Disabled": false,
    "DNCMode": true,
    "MDCMode": true,
    "Workshop": "Building A",
    "DNCGroup": "DMU50",
    "MDCGroups": [
      "Line3"
    ]
  }
]

List all stations
GET/stations

Available from : v1.0

Licence required : any


Station KPIs

Key perfomance indicators of a station.

GET /stations/station_id/kpi?dstart=2015-06-20T17:19:00.000+02:00&dend=2015-06-30T17:19:00.000+02:00
Responses200
Headers
Content-Type: application/json
Body
{
  "Times": {
    "AT": 4678489,
    "OT": 2278489,
    "PPT": 578489,
    "RT": 438489,
    "NRT": 278489,
    "FPT": 118484,
    "FT": 22455,
    "MTBF": 21134,
    "MTTR": 5678
  },
  "Rates": {
    "TEEP": 0.45,
    "GEE": 0.6,
    "OEE": 0.68,
    "Performance": 0.9,
    "Quality": 0.95,
    "Availability": 0.8,
    "Requisition": 0.6,
    "Load": 0.8,
    "Involvement": 0.9,
    "HardwareAvailability": 0.98
  }
}

Get station KPIs
GET/stations/{station_id}/kpi{?dstart,dend}

Available from : v1.3

Licence required : monitor

Station KPIs contains the following information.

Attribute name Description
Times All time KPIs expressed in seconds.
Rates All rates KPIs expressed in percents.

Times :

Attribute name Description NFE60-182 Terminology
AT All time included in the selected period (24/7) Temps total
OT Opening time in CNC calendar. Temps d’ouverture
PPT Planned production time. Temps requis
RT Run Time. Temps de fonctionnement
NRT Net Run Time Temps net
FPT Fully Productive Time Temps utile
FT Failure Time Temps de panne
MTBF Mean Time Between Failure. Temps moyen entre les pannes
MTTR Mean Time To Repair. Temps moyen de dépannage

Rates :

Attribute name Description NFE60-182 Terminology
TEEP Total Effective Equipment Performance Taux de rendement économique (TRE)
GEE Global Equipment Effectiveness Taux de rendement global (TRG)
OEE Overall Equipment Effectiveness Taux de rendement synthétique (TRS)
Performance Performance rate Taux de performance (TP)
Quality Quality rate Taux de qualité (TQ)
Availability Availaibility rate Taux de disponibilité opérationelle (DO)
Requisition NC Taux de réquisition
Load NC Taux de charge
Involvement NC Taux stratégique d’engagement
HardwareAvailability NC Taux de disponibilité matérielle

For any question regarding KPIs terminology or calculations, please read OEE rules or ask our team.

URI Parameters
HideShow
station_id
number (required) Example: 7

ID of the station

dstart
datetime (required) Example: 2015-06-20T17:19:00.000+02:00

Period start selection

dend
datetime (optional) Example: 2015-06-30T17:19:00.000+02:00

Period end selection (default = now)


State

Ressources related to CWork’s station state definitions.

State

GET /states/state_id
Responses200
Headers
Content-Type: application/json
Body
{
  "Handle": 4,
  "Name": "Disengagement",
  "Color": "#808080",
  "OEECategory": 1,
  "ParentHandle": null,
  "CloseDay": true,
  "ProdPercent": false,
  "UsePercent": false
}

View a state definintion
GET/states/{state_id}

Available from : v1.0

Licence required : any

A state object has the following attributes:

Attribute name Description
Handle Unique identifier. Also known as ‘state_id’.
Name The name of the state.
Color Color of the state (Hexadecimal format).
TPM State category in the OEE norm.
ParentHandle Unique identifier of the state’s parent state.
CloseDay Wether or not the state ends the day if placed last.
ProdPercent Wether or not counting in the production percentage.
UsePercent Wether or not counting in the usage percentage.
URI Parameters
HideShow
state_id
number (required) Example: 4

ID of the state


State list

GET /states
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "Handle": 0,
    "Name": "Production",
    "Color": "#008000",
    "OEECategory": 4,
    "ParentHandle": null,
    "CloseDay": false,
    "ProdPercent": true,
    "UsePercent": true
  },
  {
    "Handle": 1,
    "Name": "Breakdown",
    "Color": "#FF0000",
    "OEECategory": 2,
    "ParentHandle": null,
    "CloseDay": false,
    "ProdPercent": false,
    "UsePercent": true
  },
  {
    "Handle": 2,
    "Name": "Setting",
    "Color": "#0000FF",
    "OEECategory": 2,
    "ParentHandle": null,
    "CloseDay": false,
    "ProdPercent": false,
    "UsePercent": true
  },
  {
    "Handle": 3,
    "Name": "Waiting",
    "Color": "#FFFF00",
    "OEECategory": 3,
    "ParentHandle": null,
    "CloseDay": false,
    "ProdPercent": false,
    "UsePercent": true
  },
  {
    "Handle": 4,
    "Name": "Disengagement",
    "Color": "#808080",
    "OEECategory": 1,
    "ParentHandle": null,
    "CloseDay": true,
    "ProdPercent": false,
    "UsePercent": false
  }
]

List all states
GET/states

Available from : v1.0

Licence required : any


Station status

Ressources describing the real time status of a stations. This is useful if you want to build a dashboard for example.

Station status

GET /station_statuses/station_id
Responses200
Headers
Content-Type: application/json
Body
{
  "Reference": "C138568-304",
  "Order": "588558",
  "Job": "30",
  "State": {
    "Handle": 2,
    "Name": "Setting",
    "Color": "#0000FF",
    "OEECategory": 2,
    "ParentHandle": null,
    "CloseDay": false,
    "ProdPercent": false,
    "UsePercent": true
  },
  "LastTop": "2015-10-29T16:58:00.000+01:00",
  "Comment": "Setting for next job (588558-30)"
}

View a station's status
GET/station_statuses/{station_id}

Available from : v1.0

Licence required : monitor

A station object has the following attributes:

Attribute name Description
Reference Part reference associated with the currently running Order
Order The name of the currently running Order
Job The name of the currently running Job
State State object representing the current state of the station.
LastTop Date of the last state change.
Comment Comment of the last state change. v1.1
URI Parameters
HideShow
station_id
number (required) Example: 4

ID of the station


Documents and Versions

Ressource representing a CWork document.

Document

Access a specific document.

GET /documents/doc_id
Responses200
Headers
Content-Type: application/json
Body
{
  "DocumentId": 7,
  "Reference": "HSC70",
  "Extension": "MPF",
  "Folder": "",
  "StationId": 17,
  "DisplayStatus": "VALIDATED",
  "DisplayIndex": "A/5",
  "DisplaySize": 13453,
  "Emergency": 2,
  "CDate": "2015-06-28T17:19:00.000+02:00",
  "MDate": "2015-06-30T17:00:07.000+02:00",
  "Custom1": "foo",
  "Custom2": "bar",
  "Custom3": "alpha",
  "Custom4": "beta",
  "Custom5": "omega",
  "Protected": true,
  "Archived": false
}

Get Document
GET/documents/{doc_id}

Available from : v1.3

Licence required : dnc

A document object has the following attributes:

Attribute name Description
DocumentId Unique document identifier. document_id
Reference The reference of the document in CWork
Extension File extension of the document
StationId Identifier of the station owning the document
Folder Name of the folder holding the document (empty if in station’s root) ex : folder1\
DisplayStatus Status of the current version in display (!!see doc for details!!)
DisplayIndex Index of the current version in display (!!see doc for details!!)
DisplaySize Size of the current version in display (!!see doc for details!!)
Emergency Value of Emergency field in CWork.
CDate Create date of the document.
MDate Last modification date of the document.
Custom1 Value of first custom field (aka : Description)
Custom2 Value of second custom field (aka : Title)
Custom3 Value of third custom field (aka : Subject)
Custom4 Value of fourth custom field (aka : Category)
Custom5 Value of fifth custom field (aka : Manuel index)
Protected true if the document is marked as protected in the software
Archived true if the document is marked as archived in the software
URI Parameters
HideShow
doc_id
number (required) Example: 4

ID of the document


Document list

List all documents.

GET /documents?reference=HSC80&extension=MPF&station=17&limit=50&page=1
Responses200
Headers
Content-Type: application/json
Body
{
  "Has_more": false,
  "Documents": [
    {
      "DocumentId": 7,
      "Reference": "HSC80",
      "Extension": "MPF",
      "Folder": "",
      "StationId": 17,
      "DisplayStatus": "VALIDATED",
      "DisplayIndex": "A/5",
      "DisplaySize": 13453,
      "Emergency": 2,
      "CDate": "2015-06-28T17:19:00.000+02:00",
      "MDate": "2015-06-30T17:00:07.000+02:00",
      "Custom1": "foo",
      "Custom2": "bar",
      "Custom3": "alpha",
      "Custom4": "beta",
      "Custom5": "omega",
      "Protected": true,
      "Archived": false
    },
    {
      "DocumentId": 8,
      "Reference": "HSC80",
      "Extension": "MPF",
      "Folder": "random-folder\\",
      "StationId": 17,
      "DisplayStatus": "TESTING",
      "DisplayIndex": "B/2",
      "DisplaySize": 1453,
      "Emergency": 0,
      "CDate": "2015-06-28T17:19:00.000+02:00",
      "MDate": "2015-06-30T17:00:07.000+02:00",
      "Custom1": "foo",
      "Custom2": "bar",
      "Custom3": "alpha",
      "Custom4": "beta",
      "Custom5": "omega",
      "Protected": false,
      "Archived": false
    }
  ]
}

List all documents
GET/documents{?reference,extension,station,limit,page}

Available from : v1.3

Licence required : dnc

The list will be built as follows.

Attribute name Description
Has_more True if there is more page to be loaded.
Documents List of Document object

You can filter the list with the following parameters

URI Parameters
HideShow
reference
string (optional) Example: HSC80

Exact reference of the document

extension
string (optional) Example: MPF

File extension of the document

station
integer (optional) Example: 17

id of the station owning the document (we will consider station in the same group)

limit
integer (optional) Example: 50

Count of document per page (default = 200; max = 200)

page
integer (optional) Example: 1

Page number (default = 1)


Create a document

POST /documents
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "Reference": "HSC70",
  "StationId": 17,
  "Extension": "MPF",
  "Folder": "",
  "Custom1": "foo",
  "Custom2": "bar",
  "Custom3": "alpha",
  "Custom4": "beta",
  "Custom5": "omega",
  "Protected": false,
  "Archived": false
}
Responses201
Headers
Content-Type: application/json
Body
{
  "DocumentId": 7,
  "Reference": "HSC70",
  "Extension": "MPF",
  "Folder": "",
  "StationId": 17,
  "DisplayStatus": "",
  "DisplayIndex": "",
  "DisplaySize": 0,
  "Emergency": 0,
  "CDate": "2015-06-38T17:19:00.000+02:00",
  "MDate": "2015-06-38T17:19:00.000+02:00",
  "Custom1": "foo",
  "Custom2": "bar",
  "Custom3": "alpha",
  "Custom4": "beta",
  "Custom5": "omega",
  "Protected": false,
  "Archived": false
}

Create a document
POST/documents

Available from : v1.3

Licence required : dnc

Create a new document in the system. Your can have the following fields :

Attribute name Description
Reference Target reference for the new document.
StationId Target station identifier for the document.
Extension Extension of the new document.
Folder Folder in which to place the document.
Custom1 Value of first custom field (aka : Description)
Custom2 Value of second custom field (aka : Title)
Custom3 Value of third custom field (aka : Subject)
Custom4 Value of fourth custom field (aka : Category)
Custom5 Value of fifth custom field (aka : Manuel index)
Protected Set to true to mark the document as protected
Archived Set to true to mark the document as Archived

Reference and StationId are required fields in your request. All other fields may be omitted.


Version

Access a specific version based on it’s identifier.

You can also acess this resource directly by addressing your request to /versions/{ver_id}

GET /documents/doc_id/versions/ver_id?include_file=true
Responses200
Headers
Content-Type: application/json
Body
{
  "VersionId": 38,
  "DocumentId": 27,
  "Status": "VALIDATED",
  "PrimaryIndex": "B",
  "SecondaryIndex": "9",
  "CDate": "2015-06-28T17:19:00.000+02:00",
  "MDate": "2015-06-30T17:00:07.000+02:00",
  "RXDate": "2015-05-30T17:00:07.000+02:00",
  "TXDate": "2015-06-21T17:00:07.000+02:00",
  "Comment": "foo",
  "Size": 15898,
  "File": {
    "url": "rGBV84pC3a",
    "md5": "60D48FC210A6AF24F9845DBF3645623BFDC793AB"
  }
}

Get version
GET/documents/{doc_id}/versions/{ver_id}{?include_file}

Available from : v1.3

Licence required : dnc

A version object has the following attributes:

Attribute name Description
VersionId Unique version identifier. version_id.
DocumentId Unique identifier of the document owning the version.
Status Status associated with the version.
PrimaryIndex Primary index of the version.
SecondaryIndex Secondary index of the version.
CDate Date of creation.
MDate Date of last modification
RXDate Date of reception.
TXDate Date of last send.
Comment Comment on the version.
Size File size in byte of the version.
File Structure holding the download temp file name and a md5 hash to control it’s integrity. Blank if include_file is false. The temp file will be deleted under 10min.
URI Parameters
HideShow
doc_id
number (required) Example: 27

ID of the document object

ver_id
number (required) Example: 38

ID of the version object

include_file
boolean (optional) Example: true

If set to true, will add the url to obtain the file. Delfault is false.


Version list

GET /documents/doc_id/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "VersionId": 38,
    "DocumentId": 27,
    "Status": "VALIDATED",
    "PrimaryIndex": "B",
    "SecondaryIndex": "9",
    "CDate": "2015-06-28T17:19:00.000+02:00",
    "MDate": "2015-06-30T17:00:07.000+02:00",
    "RXDate": "2015-05-30T17:00:07.000+02:00",
    "TXDate": "2015-06-21T17:00:07.000+02:00",
    "Comment": "foo",
    "Size": 15898,
    "File": null
  },
  {
    "VersionId": 39,
    "DocumentId": 27,
    "Status": "TESTING",
    "PrimaryIndex": "B",
    "SecondaryIndex": "10",
    "CDate": "2015-06-29T17:19:00.000+02:00",
    "MDate": "2015-06-30T17:00:07.000+02:00",
    "RXDate": "2015-05-30T17:00:07.000+02:00",
    "TXDate": "2015-06-21T17:00:07.000+02:00",
    "Comment": "bar",
    "Size": 15695,
    "File": null
  }
]

List all versions within a document.
GET/documents/{doc_id}/versions

Available from : v1.3

Licence required : dnc

List of Version object

NB : The include_file option is not available when listing all versions of a document. If you want to obtain the file behind a version, make a GET request to /documents/{doc_id}/version/{ver_id} or directly at /versions/{ver_id}

URI Parameters
HideShow
doc_id
number (required) Example: 27

ID of the document


POST /documents/doc_id/versions
Requestswith md5without md5
Headers
Content-Type: application/json
Body
{
  "File": "rGBV84pC38",
  "Md5": "60D48FC210A6AF24F9845DBF3645623BFDC793AB",
  "Comment": "my new version"
}
Responses201
Headers
Content-Type: application/json
Body
{
  "VersionId": 38,
  "DocumentId": 27,
  "Status": "VALIDATED",
  "PrimaryIndex": "B",
  "SecondaryIndex": "9",
  "CDate": "2015-06-28T17:19:00.000+02:00",
  "MDate": "2015-06-30T17:00:07.000+02:00",
  "RXDate": "2015-05-30T17:00:07.000+02:00",
  "TXDate": "2015-06-21T17:00:07.000+02:00",
  "Comment": "my new version",
  "Size": 15898,
  "File": null
}
Headers
Content-Type: application/json
Body
{
  "File": "rGBV84pC38",
  "Md5": "",
  "Comment": ""
}
Responses201
Headers
Content-Type: application/json
Body
{
  "VersionId": 38,
  "DocumentId": 27,
  "Status": "VALIDATED",
  "PrimaryIndex": "B",
  "SecondaryIndex": "9",
  "CDate": "2015-06-28T17:19:00.000+02:00",
  "MDate": "2015-06-30T17:00:07.000+02:00",
  "RXDate": "2015-05-30T17:00:07.000+02:00",
  "TXDate": "2015-06-21T17:00:07.000+02:00",
  "Comment": "",
  "Size": 15898,
  "File": null
}

Submit a version
POST/documents/{doc_id}/versions

Available from : v1.3

Licence required : dnc

Submit a version to the system. Your request will have to contain the following fields :

Attribute name Description
File Name of the temporal file submited to the system.
Md5 Md5 hash allowing us to check the integrity of the transmited file (optional).
Comment Comment to set to the version (optional)
URI Parameters
HideShow
doc_id
number (required) Example: 27

ID of the document


Orders & Jobs

Comming soon…

Generated by aglio on 02 Oct 2017