4 Reference

Source: This article refers to 4 Reference
Note: Coresystems uses OAuth 2.0 for authorization. For more information on OAuth 2.0, including information, refer to the following topic.

4.1 Directory Service

The service is the main entry point for accessing the Coresystems services. Directory service provides the Cluster NodeURL for the given account name.The base URL for requests to Directory Service is:

https://ds.coresuite.com/ds

4.1.1 GET Account

Retrieves an account specified by its name. The response contains the Cluster Node URL for the account which you will use as base URL for the rest of APIs

GET https://ds.coresuite.com/ds/api/directory/v1/accounts/{accountName}
Parameter name Type Description
accountName string Requested account name. Must be properly URL encoded, see HTML URL Encoding Reference

4.1.1.1 Response

{ "accountName": "name of the account", "clusterName": "code of the cluster", "URL": "cluster node URL"}

4.1.1.2 Example

Request

GET /ds/api/directory/v1/accounts/test HTTP/1.1
Host: ds.coresuite.com

Response

HTTP 200 OK Content-Type: application/json { "accountName": "test", "clusterName": "IE", "URL": :"https://eu.coresuite.com" } 

4.2 Company API

The service provides a way of retrieving information about companies linked to the cloud account.The base URL for requests to Company API must be retrieved from the Directory Service


4.2.1 GET Companies

Retrieves a list of companies associated with the given account.

GET https://www.baseURL.com/masterCloudInterface/informationService/companies

4.2.1.1 GET Company HTTP Header Parameters

Property Value
Accept Required: Defines in which format the service should return the data. Either 'application/text' or 'application/json'.

4.2.1.2 GET Company Response

‘application/json’

Value Description
{ "companies" : [ { "name" : "companyName", "description" : "companyDescription", }, { "name" : "company2Name", "description" : "company2Description", } ] }

A list of the available companies for the cloud user will be delivered with the associated data cloud seperated by new line character. Be aware that the list could be empty which doesn't indicate a failure but rather expresses that the user isn't assigned to a company.

4.3 Data API

Data Api is a RESTfull API and the operations are based on resources. It’s important to know that for each resource we have multiple representations called DTOs and this are used to pass the data around.For more details please read our Data Model

The base URL for requests to Data API is the cluster node URL like

https://eu.coresuite.com

4.3.1 Retrieving an Individual Resource

In order to retreive an individual resource the following HTTP GET request has to be made:

GET https://www.baseURL.com/api/data/{v4}/{resourceName}/{resourceId}?dtos={resourceName.dtoVersion}
Parameter name Type Description
resourceName string Name of the resource you are retrieving. The list of available resources can be found on this page.
resourceId string A unique identifier of the resource. It is GUID in the form: "XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
v4 string An identifier for the version of the resource that is being requested. Versions will start from 4 and subsequent versions will follow the convention 5, ... n
dtos list<string>

A list of strings containing {resourceName.dtoVersion} pairs (separated by ";"). This parameter is MANDATORY on all requests. The list must contain a pair for each DTO expected in the response, be it the primary requested DTO or ones that result from "expands". This way the cloud always knows which DTOs and versions are expected by a query.


4.3.2 Retrieving Lists of Objects

In order to retreive all resources of a given type the following HTTP GET request has to be made

GET https://www.baseURL.com/api/data/{v4}/{resourceName}?dtos={resourceName.dtoVersion}

4.3.3 Pagination

Requests that return multiple items that don’t specify paging parameters will be paginated to 20 items by default.

You can specify paging information with thepageparameter. You can also set a custom page size up with thepageSizeparameter, the maximum value is limited by signed 32-bit integer range (2^31-1). However, for performance reasons on both client and server side, use a reasonable pageSize.


4.3.4 Sorting

Requests that return multiple items can be sorted ascending or descending using the orderByparameter.

The value of this parameter should specify the name of a field from the top level fields of the resource being requested.

Alternatively, the parameter can have a value from the set of predefined sort orders (asc, desc).

The predefined sort order return custom sort order and are used in cases where the result set should be sorted by a complex criteria.

Example:

GET https://www.baseURL.com/api/data/v4/Address?dtos={resourceName.dtoVersion}&orderBy=city,name desc,businessPartner.name

As you can see you can also sort based on some field from the referenced object


In order to retrieve a resource that match certain condition on its attributes the following request has to be made:

GET https://www.baseURL.com/api/data/v4/{resourceName}?query=CQL

CQL (Cloud Query Language) is a simple query language that supports queries over a resource in the following format.

searchCriteria1 OP value1 LOGICAL_OPERATOR searchCriteria2 OP value2 LOGICAL_OPERATOR searchCriteria3 OP value3  

Example (not-URL encoded for readability purposes):

https://www.baseURL.com/servicecloud/v1/ServiceCall?query=status != Open AND startDateTime &gt; "2014-01-01T00:00:00Z" AND (businessPartner.name = "John Doe" OR businessPartner.name = "Ion Quest")

CQL parameter Description
searchCriteria1, 2 ... n

Can represent the following:

  • name of a field of a resource.
    • E.g. if the resource is businessPartner search criteria can be name of fields of the business partner: name, code, etc
  • name of a field of a linked resource by a one to one or one to many relationship using the convention LinkedResource.LinkedResourceFieldName.
    • E.g. if the resource is serviceCall and the serviceCall resource has a businessPartner field (one to one relation) and a search must be performed to find all service calls of business partner called "john" the searchCriteria will be businessPartner.name = "john"
    • E.g. if the resource is activity and the activity resource has a object field (complex field, one to one relation) referencing a businessPartner resource and a search must be performed to find all activities of business partner called "john" the searchCriteria will be object.objectId(BusinessPartner).name= "john"
  • special case for searching on fields of embedded objects, e.g. fields of type ObjectRef, in this case the convention is object.objectId
    • E.g. if the resource is businessPartner and we want to get all his addresses, we'd search for Address?query=object.objectId = "<businessPartner id>"
  • a reserved search criteria name from a list of predefined reserved names that triggers a special search behavior.
    • E.g. it is required to search for all serviceCalls at the address "Mircea Eliade 8". This query would require to search in all the addresses of the business partners that have service calls at that address. There's a many to many relationship between address and business partner.
    • To perform this query a reserved search criteria should be defined in the cloud and used in the query. Predefined search criterias will use a function format (to accept multiple parameters) returning boolean value, e.g. searchByBusinessPartnerAddress("Mircea Eliade 8").
      (No predefined search criterias exist yet)
  • functions can be used to build more advanced search criterias:
    • CONTAINS (field_name, value) - returns true if value of the specified field contains the provided value, or false otherwise. At the moment this function can be used only with fields which store lists of identifiers or domain object models. E.g. to retrieve attributes defined for fileLibrary the query condition would be : CONTAINS (objectTypes, "FILEREVISION").
    • me() - will be evaluated to the identifier of the current user used to make the request. E.g. to retrieve a list of object not modified by me the query condition would be : lastChangedBy != me()
OP

Represents a value operator from the predefined set:

  • = equality operator
  • != not-equal operator
  • >, <, >=, <= mathematical operators. Should only be used on number or date fields.
  • ! negation operator used on boolean expressions.
  • ilike operator. If used, a wildcard case-insensitive match should be performed on the value. The value can contain % as a substitute for zero or more characters. E.g. ?query=subject ilike "%abc%".
  • like operator. If used, a wildcard case-sensitive match should be performed on the value. The value can contain % as a substitute for zero or more characters. E.g. ?query=subject ilike "%abc%".
  • in operator. If used the left operand value will be check for equality against the set of values provided in the right operand value (works the same way as sql in operator). E.g. ?query=code in (1, 2, 3).
  • is operator used on checking whether resource field has a null value. E.g. query=code is null.
value1, 2 ... n

Represents the value a search criteria should have in order to be included in the search.

String values should be enclosed between double quotes " ".

If the value contains the % operator, the % should be escaped using %.

LOGICAL_OPERATOR

Represents an operator from the set of the following predefined operators: AND, OR

ORDER BY, ORDER BY DESC

This will not be part of the CQL, but a separate parameter. See sorting section above.


4.3.5.1 Search Fields

DTO field names are used when building CQL query expression. Generally the a field can of one of the following types:

Field Type Description
Simple Regular field of a primitive type
Complex

FIelds with complex structure containing one or more simple (embedded) field inside (e.g. Activity#object).
Embedded fields of a complex field are referenced using '.' : object.objectType.

Reference A field which contains an identifier referencing another object
Alias "Virtual" field created by expand on inversed relation. Using alias in CQL is no different from using regular fields.
Collection
(not supported in CQL)
A collection of values

Note: For reference fields it’s possible to specify explicitly the type of the referenced resource, e.g. fieldName(ReferencedResource). This is particularly useful when objectfield*(e.g. Activity#object.objectId) is involved in the CQL expression, as the referenced resource type can not be inferred from the DB schema. For all *objectfields involved in the CQL query referenced resource type must be explicitly defined. E.g. in case of Activity valid field expressions are: createPerson, object.objectId(BusinessPartner), etc.


4.3.5.2 Search Values

As the CQL query language vocabulary contains some lexemas which overlap with HTTP URL reserved characters, the CQL query has to be HTTP encoded.

Value Type Format Example (raw) Example (encoded)
Integer value query=amount=123 query=amount%3D123
Double value query=amount=123.45 query=amount%3D123.45
Boolean value query=partOfRecurrenceSeries=true query=partOfRecurrenceSeries%3Dtrue
Timestamp value query=lastchanged=1396267445390 query=lastchanged%3D1396267445390
Identifier "value" query=id="XXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXX" query=id%3D%22XXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXX%22
String "value" query=name="Billy" query=name%3D%22Billy%22
Datetime "value" query=dueDateTime="2000-01-01T00:00:00Z" query=dueDateTime%3D%222000-01-01T00%3A00%3A00Z%22

Resource field of any type can have nullvalue. In this case is operator should be used to check if the field value is null (e.g. query=name is null). To that is not null, you can use query=!(name is null)


4.3.6 Response Shaping

The response shape for queries returning either one object or a list of objects can be dynamically requested by the client, i.e. the client can say “give me the entire object, all fields” or “give me only these fields of the object”.

Shaping is done by using “fields=field1,field2,…” in the request, where “field1, field2…” are names of the fields in the DTO description.

By default, if the parameter “field” is missing, the cloud returns the complete object (all fields).

Example:

GET https://www.baseURL.com/api/data/v4/ServiceCall/{guid}?fields=id,subject

4.3.7 Expanding Queries

In many cases clients might need to eagerly fetch data from related entities to the base entity they’re querying for. For example, when showing a list of Service Calls we might need to show also each Service Call Business Partner’s name. Or, when showing a Business Partner’s details, we need to know whether he has any Service Calls, so we can show a navigation link to them. For these (and other) cases the API will support the “expand” concept.

Expand will support only 1-1, n-1 and 1-n relations. n-n relations are not present in the cloud.

There are several ways of using the expand keyword:

Case Example Explanation
Expand a complete related entity, based on a field name
GET https://www.baseURL.com/api/data/v4/ServiceCall/{id}?
    expand=businessPartner
Will return the ServiceCall plus its related BusinessPartner. "businessPartner" is a field on the ServiceCall DTO.

Expand a shaped related entity

GET https://www.baseURL.com/api/data/v4/ServiceCall/{id}?
    expand=businessPartner;fields=city,name 
Will return the ServiceCall plus its related BusinessPartner which contains only the "city" and "code" fields + Contact with the field "lastName". "businessPartner" and "contact" are fields on the ServiceCall DTO.
Multiple/mixed expand
GET https://www.baseURL.com/api/data/v4/BusinessPartner/{id}?
    expand=count(serviceCalls)&amp;
    expand=count(addresses)&amp;
    expand=paymentTerm&amp;
    expand=group;fields=name,code 
Search expand
https://www.baseURL.com/api/data/v4/{resourceName}?expand=...
All of the single-entity expand functionality should work identically when searching.
Expand an "object" relationship (based on the object property, which could represent any object)
GET https://www.baseURL.com/api/data/v4/Activity/{id}?
    expand=object.objectId(BusinessPartner);fields=id,city&amp;
    expand=object.objectId(ServiceCall) 
Will return the Activity plus its related BusinessPartner (partial, only id and city fields) or ServiceCall, if they are the ones referred to by the Activity.Object property. If the Activity.Object property refers to another object than BusinessPartner or ServiceCall, nothing will be expanded and just the Activity will be returned. The response will contain the expanded object under 'object(TYPE)' field.
the URL must always include a "dtos" property
GET https://www.baseURL.com/api/data/v4/Activity/{id}?
    expand=object.objectId(BusinessPartner)&amp;
    expand=object.objectId(ServiceCall)&amp;
    dtos=Activity.9;BusinessPartner.10;ServiceCall.8 

If you are interested in a more powerful way of querying, please visit Query API.


4.3.7.1 Permissions

In case there are no READ permissions for expanded resource available there will be no expanded objects returned.


4.3.8 Creating Objects

In order to create a new object, a POST request has to be made to following URL:

POST https://www.baseURL.com/api/data/v4/{resourceName}?dtos={resourceName.dtoVersion}

The POST request body should contain the new resource that is being created. If no ID is specified in the resource, it will be generated by the cloud; otherwise the resource is created with the specified one.

NOTE: Objects can be created also with PUT request in case the ID is known. See Updating existing objects

Here is an overview of supported query parameters:

Query Parameter Type Required Description
forceUpdate Boolean false

Set to false by default. If set to true, the optimistic locking mechanism provided by lastChanged property is ignored. Such a call overrides any possible changes made to the resource since the last retrieval. (Such a situation may occur only if ID is specified)

If the resource has been created successfully, the server has to do the following:


4.3.9 Updating Existing Objects

In order to update an existing object, a PUT or PATCH request has to be made to following URL:

PUT/PATCH https://www.baseURL.com/api/data/v4/{resourceName}/{resourceId}?dtos={resourceName.dtoVersion}

In case you use PUT the request should contain in the body the entire updated resource.

In case you use PATCH the request should contain in the body the fields that you want to update.

If the resource does not exist, this server will create it under the given URI.Please note that this is valid also for Patch, but you need to send all required fields in order to create a valid object.

Here is an overview of supported query parameters:

Query Parameter Type Required Description
forceUpdate Boolean false

Set to false by default. If set to true, the optimistic locking mechanism provided by lastChanged property is ignored. Such a call overrides any possible changes made to the resource since the last retrieval.

Response

  • status code 201
  • response body contains the updated (created) resource


4.3.9.1 Partial Updates

Basic functionality for this is described above in Updating existing objects. Below you can find some specific details :

  • Partial updates (sending only the fields that are being updated) are supported. For deleting a field’s value, the api will accept “null” on that field.

  • Special notes : you cannot do a partial update on the fields of inlined objects, like UdfValue or ObjectReference. For such objects, you still need to send all fields.


4.3.10 Delete Existing Objects

In order to delete an existing object, a DELETE request has to be made to following URL:

DELETE /api/data/v4/{resourceName}/{resourceId} HTTP/1.1

Here is an overview of supported query parameters:

Query Parameter Type Required Description
lastChanged Number true

Last changed timestamp of the object to be deleted.

forceDelete Boolean false

Set to false by default. If set to true, the optimistic locking mechanism provided by lastChanged property is ignored. Such a call overrides any possible changes made to the resource since the last retrieval.

To delete a resource, lastChanged parameter should be provided to ensure that client is deleting the latest version.

An example of a simple HTTP request to delete a business partner object by its id would be:

Request

DELETE /api/data/v4/BusinessPartner/8BA36AE6-079D-45EF-8DDE-D601020B6698?lastChanged=1351620288374

Response

 HTTP/1.1 200 OK

An object with cloud id 8BA36AE6-079D-45EF-8DDE-D601020B6698 will be deleted.


4.3.11 Retrieve Deleted IDs of Resource

In order to retreive the deleted ids of a particular resource the following HTTP GET request has to be made

GET https://www.baseURL.com/api/data/v4/{resourceName}/deleted?dtos={dtos}&from={from}&to={to} 

Here is an overview of supported query parameters:

Query Parameter Type Required Description
resourceName String true Name of the resource you are retrieving.
dtos String true

For the moment we support DeletedObjects.1 and DeletedObjects.2 dtos.

DeletedObjects.1 will return a list of cloud ids

DeletedObjects.2 will return a list of {cloudId, externalId pair}

from Number true Timestamp since you want to get deleted data. Objects deleted also in this exact timestamp will be retrieved.
to Number true Timestamp up to what date you want to get deleted data. Objects deleted also in this exact timestamp will not be retrieved.

An example of a simple HTTP request to retrieve deleted ids of a business partner would be:


4.3.12 External ID Operations

In order to support easier integration with other systems, all DTOs that extend SyncObjectDto_V9 or above have a field called externalId. This field is used to store the id of that object from the external system that you integrate.

Operations with an external Id were added to allow you to work just with external Id and ignore the cloudId. More benefits of doing this can be found in Integration guidelines


4.3.12.1 Retrieve an Individual Resource by External ID

In order to retreive an individual resource by external Id the following HTTP GET request has to be made

GET https://www.baseURL.com/api/data/v4/{resourceName}/externalId/{externalId}?dtos={resourceName.dtoVersion} 

Here is an overview of supported query parameters:

Query Parameter Type Required Description
useExternalIds Boolean false Set to false by default. If set to true, the references to other objects will contain also the externalId of the referenced object

All the same functionality for retrieving an individual resource, like shaping, searching, expanding etc is supported


4.3.12.2 Create Objects with External ID

In order to create a new object that contains external Id use the same logic as for Creating objects.

You will need to use a dto version that supports externalId and pass a value for that field. Dtos that inherit SyncObjectDto_V9 or above will contain the externalId field. The field values supplied here must be unique.

GET https://www.baseURL.com/api/data/v4/{resourceName}/externalId/{externalId}?dtos={resourceName.dtoVersion} 

4.3.12.3 Update Existing Objects by External ID

In order to update an existing object by external id, a PUT or PATCH request has to be made to following URL:

PUT/PATCH https://www.baseURL.com/api/data/v4/{resourceName}/externalId/{externalId}?dtos={resourceName.dtoVersion}

In case you use PUT, the request should contain in the body the entire updated resource.

In case you use PATCH, the request should contain in the body the fields that you want to update.

If the resource does not exist, this server will create it under the given URI.Please note that this is valid also for Patch, but you need to send all required fields in order to create a valid object.

Here is an overview of supported query parameters:

Query Parameter Type Required Description
forceUpdate Boolean false

Set to false by default. If set to true, the optimistic locking mechanism provided by lastChanged property is ignored. Such a call overrides any possible changes made to the resource since the last retrieval.

Response

  • status code 201
  • response body contains the updated (created) resource
  • error codes : CA-146, CA-147

Since you are using only external ids, then you have also the possibility to upload data that contains references with externalId instead of cloud Id

Example request with externalId references

Example response with externalId references


4.3.12.4 Delete Existing Objects by External ID

In order to delete an existing object, a DELETE request has to be made to following URL:

    

DELETE /api/data/v4/{resourceName}/externalId/{externalId} HTTP/1.1

Here is an overview of supported query parameters:

Query Parameter Type Required Description
lastChanged Number true

Last changed timestamp of the object to be deleted.

forceDelete Boolean false

Set to false by default. If set to true, the optimistic locking mechanism provided by lastChanged property is ignored. Such a call overrides any possible changes made to the resource since the last retrieval.

To delete a resource, lastChanged parameter should be provided to ensure that client is deleting the latest version.

An example of a simple HTTP request to delete a business partner object by its id would be:

  
DELETE https://www.baseURL.com/api/data/v4/BusinessPartner/externalId/ExtIdBP122FS8B?lastChanged=1351620288374 HTTP/1.1
    
HTTP/1.1 200 OK

The object with external id ExtIdBP122FS8B will be deleted.


Retrieve deleted external ids of an resource

More details at Retrieve deleted objects

    GET /api/data/v4/BusinessPartner/deleted?dtos=DeletedObjects.2&from=1440765076962&to=1442230064023 HTTP/1.1
HTTP/1.1 200 OK { "deletedIds": [ {"id" : "CE037D0236CB49AF8D22EFB6DA1E9409", "externalId" : "BPExtId1"}, {"id" : "AE037D0236CB49AF8D22EFB6DA1E9411", "externalId" : "BPExtId2"}, {"id" : "WOW37D0236CB49AF8D22EFB6DA1E9420"} //in case this object has no externalId set. ]}

4.4 Batch API

4.4.1 Introduction

This section shows how to batch API calls together to reduce the number of HTTP connections your client has to make. It also allows to transactionally execute a sequence of API calls. The API was inspired by https://cloud.google.com/storage/docs/json_api/v1/how-tos/batch, but we made several differences in the concept (transactional processing by default, order of the requests is kept, etc.)

See also :


4.4.1.1 Batch Request

A batch request consists of multiple API calls combined into one HTTP request. The requests are processed sequentially and in the given order. The number of requests in a single batch is limited to 1000.

A batch request is a single standard HTTP request containing multiple API calls (Data API , Query API or in general any other API we have) using the multipart/mixed content type. Within that main HTTP request, each of the parts contains a nested HTTP request.

Each part begins with its own Content-Type: application/http HTTP header. It can also have an optional Content-ID header. However, the part headers are just there to mark the beginning of the part; they’re separate from the nested request. After the server unwraps the batch request into separate requests, the part headers are ignored.

The body of each part is itself a complete HTTP request, with its own method, URL, headers, and body. The HTTP request must only contain the path portion of the URL; full URLs are not allowed in batch requests.

Authentication is taken from the batch request - that means that each part’s HTTP request do not need to contain the Authentication query parameters or headers as they inherit the authentication context from the parent batch request.

Host cluster URL retrieved from the Directory API for example https://eu.coresuite.com
Path /api/data/batch/v1/
Method POST
Query Parameters transactional

Optionalhttps://app.cloudcannon.com/editor#. If not set, defaults to true.

If set to true, all of the batched requests will be executed within a single transaction. That means that either all of them successfully pass, or if any fails, the processing stops (nor more requests will be processed) and all the changes are rolled back.

If set to false, all batched requests will be executed regardless whether they pass or fail.

Headers Content-Type

Must be set to multipart/mixed with defined boundary parameter.

4.4.1.2 Batch Response

The server’s response is a single standard HTTP response with a multipart/mixed content type; each part is the response to one of the requests in the batched request, in the same order as the requests.

Like the parts in the request, each response part contains a complete HTTP response, including a status code, headers, and body. And like the parts in the request, each response part is preceded by a Content-Type header that marks the beginning of the part.

If a given part of the request had a Content-ID header, then the corresponding part of the response has a matching Content-ID header, with the original value.


4.4.1.3 Batch Example

Note: Coresystems uses OAuth 2.0 for authorization. For more information on OAuth 2.0, including information, refer to the following topic.


4.4.2 Error Handling

In case of an error, services must return a correct HTTP response with an error description. In case of an error cloud returns an appropriate response status and JSON of the following structure:


4.5 Attachment API

Due to the nature of HTTP protocol, the handling of binary content is done in a special way. Attachment API is a set of services which deliver access to the fileContent field inside any attachment object.

Attachment represents a binary file together with name, description and a reference to any other object. This object gets usually linked to activities where one can attach photos and audio notes or even pdf documents and other documents (depending on the client).

This can be useful to transmit manuals or weekly detail reports to the field people.


4.5.1 Create

Create a new attachment object, and include your binary file as base64 encoded string in the fileContent field.


4.5.2 Read

The fileContent field is not filled when sending the Attachment object to the client. Please use the method descibed below:

GET https://host[:port]/dataCloudInterface/attachmentService?guid=[attachmentId]&operation=download

4.5.2.1 Response Headers

Property Value
Content-Disposition Contains the file name.
Content-Encoding Defines the encoding used.
Content-Type Defines the type of response.

4.5.3 Update

Updating is currently not supported.


4.5.4 Delete

In order to delete the content of an attachment, use the delete operation on attachment object.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.