CRUD Operations

The API gives us a way of executing the basic operations of Create, Retrieve, Update, and Delete against any module installed in the associated coreBOS. Obviously, permission restrictions exist for the connected user as if he were inside coreBOS itself.

Create

The Create operation also supports a virtual meta-field named relations which contains an array of web service IDs with which we want to relate the record being created. You can see an example of this here.

Create Inventory Modules

Inventory modules are special in many ways due to their master-detail relation with products and services, different tax mode, and support for taxes among other features. In order to support this functionality through the web service API, these modules have a set of additional rules.

Product Items/Lines

These modules support a virtual field named pdoInformation, this field contains an array of line items with this format:

    'pdoInformation' => array(
     array(
        "productid"=>2618,
        "comment"=>'cmt1',
        "qty"=>1,
        "listprice"=>10,
        'discount'=>0,  // 0 no discount, 1 discount
        "discount_type"=>'amount',  //  amount/percentage
        "discount_percentage"=>0,  // not needed nor used if type is amount
        "discount_amount"=>0,  // not needed nor used if type is percentage
      ),
      array(
        "productid"=>2619,
        "qty"=>2,
        "comment"=>'cmt2',
        "listprice"=>10,
        'discount'=>1,
        "discount_type"=>'percentage',  //  amount/percentage
        "discount_percentage"=>2,
        "discount_amount"=>0
      ),
    ),

• This is mandatory for inventory modules
• This is also supported in update
• you can see an example here

Tax Mode

Tax mode, group or individual is also mandatory. It is set with the 'taxtype' field

Product Taxes

Taxes are always applied as per system settings. In other words, you can NOT set taxes in the web service call, the taxes will be automatically set as they are defined in the application. So, if the taxtype is Group, all the available/active taxes defined in settings will be applied to the inventory record. If the taxtype is individual, the taxes configured in each product will be applied automatically.

Shipping charges and taxes

Shipping charge is set using the field 'shipping_handling_charge'.

Shipping taxes are set using the tax name defined in Settings.

Retrieve

Get all the values the user has access to, of an existent record in the application. Given a web service ID of a record this service will return an array with all the fields and their values.

Note that the way coreBOS works is that you get the values in the format of the database but you must return them in the format of the user. There is a way to inform coreBOS to accept values in database format and there is a Global Variable (Webservice_Return_FormattedValues) to retrieve values in the format of the user connected to the API.

All reference type fields which are pointing to another record will have valid web service IDs.

In all retrieve operations a series of special fields are included which contain extended information to reduce the number of network calls.

* for all reference fields with a value, we will get a virtual field with the same name of the field followed by "ename". This field contains an array of 3 values:

• module: the module of the record saved in the field (each related field may contain more than one module)
• reference: the string representation of the record, so we don't have to make another call to the coreBOS application
• cbuuid of the record
• if the module has image fields the information of the image will be returned in a virtual field with the same name of the field followed by "imageinfo".
• if the record is a user, the role name assigned to the user will also be returned

Update

This service updates ALL the fields of a given record. Once again; ALL FIELDS. This endpoint does not support updating of individual fields, so, in many cases, updating becomes a two-step operation; first retrieve all the records, assign the new values leaving the others untouched and update the whole record.

The Update operation also supports a virtual meta-field named relations which contains an array of web service IDs with which we want to relate the record being updated. You can see an example of this here.

Delete

Revise

The main difference between Revise and Update is that for revise you can send only those fields that need to be changed, but with update, you need to send all the mandatory fields to update a record.

If you send unknown fields then it will silently ignore them, the reason for this behavior is that the user may not have permission for a few fields and the system may not know if these fields are not available in the system or the user does not have permission for these fields.

CRUD Users

The current API supports the manipulation of users as if it were any other entity, that is, you can use Create, Update, Retrieve, and Query as with any other entity. The restriction is that it must be an administrator user who executes the calls, as happens within the application or you will only be able to get information about the connected user.

In order to delete a user, the DeleteUser method must be used because, as within the application and unlike the normal Delete, it is necessary to give the recipient user of the records assigned to the user that we are going to delete.

https://github.com/tsolucio/coreBOSwsDevelopment/blob/master/testcode/028lib_createUser.php

https://github.com/tsolucio/coreBOSwsDevelopment/blob/master/testcode/060lib_updateUser.php

https://github.com/tsolucio/coreBOSwsDevelopment/blob/master/testcode/070lib_deleteUser.php

Users have two other additional endpoints that permit them to change their password and Access Key.

CRUD Documents

Read full information here

Adding Comments

Most modules support the (now) standard ModComments module to manage comments on the records. Since ModComments is a normal module it can be managed using the CRUD commands indicated above.

There are two historical modules which have a non-standard way of managing comments: Support Tickets (HelpDesK) and Frequently Asked Questions (Faq). For these two modules, we have a specific endpoint: addTicketFaqComment

CRUD Mass Operations

Since network calls are very expensive we have added mass operations for the main actions.

MassCreate (MassUpsert)

The Mass Create elements structure is an intelligent layout that permits us not only to create many records in one call but also to establish relationships among the different records.

The generic structure looks like this

    [
        {
          "elementType" : "modulex",
          "referenceId" : "refRecord1",
          "element" : {
            "field" : "value"
          }
        },
        {
          "elementType" : "moduley",
          "referenceId" : "refRecord2",
          "element" : { 
            "field" : "value",
            "modulex_field" : "@{refRecord1.id}"
          }
        }
    ...
    ]

Each element of the array represents a record to be created. It contains an elementType so we know what module to create the record in, a referenceId that identifies the record inside the structure, and a field-value Object with the fields of the new record.

The reference fields in a record can reference existing records in the application but they can also reference new records that will be created using the referenceId field. This would permit us to create a Contact record and then a Potential record related to the Contact that has just been created.

An example structure to test with:

    [
        {
          "elementType" : "HelpDesk",
          "referenceId" : "",
          "element" : {
            "ticket_title":"support ticket 1",
            "parent_id":"@{refAccount1.id}",
            "assigned_user_id":"19x5",
            "product_id":"@{refProduct.id}",
            "ticketpriorities":"Low",
            "ticketstatus":"Open",
            "ticketseverities":"Minor",
            "hours":"1.1",
            "ticketcategories":"Small Problem",
            "days":"1",
            "description":"ST mass create test 1",
            "solution":"",
          }
        },
        {
          "elementType" : "HelpDesk",
          "referenceId" : "",
          "element" : {
            "ticket_title":"support ticket 2",
            "parent_id":"@{refAccount2.id}",
            "assigned_user_id":"19x5",
            "product_id":"@{refProduct.id}",
            "ticketpriorities":"Low",
            "ticketstatus":"Open",
            "ticketseverities":"Minor",
            "hours":"1.1",
            "ticketcategories":"Small Problem",
            "days":"1",
            "description":"ST mass create test 2",
            "solution":"",
          }
        },
        {
          "elementType" : "HelpDesk",
          "referenceId" : "",
          "element" : {
            "ticket_title":"support ticket 3",
            "parent_id":"@{refAccount1.id}",
            "assigned_user_id":"19x5",
            "product_id":"14x2617",
            "ticketpriorities":"Low",
            "ticketstatus":"Open",
            "ticketseverities":"Minor",
            "hours":"1.1",
            "ticketcategories":"Small Problem",
            "days":"1",
            "description":"ST mass create test 3",
            "solution":"",
          }
        },
        {
          "elementType" : "Accounts",
          "referenceId" : "refAccount1",
          "element" : {
            "accountname":"MassCreate Test 1",
            "website":"https://corebos.org",
            "assigned_user_id":"19x5",
            "description":"mass create test",
          }
        },
        {
          "elementType" : "Accounts",
          "referenceId" : "refAccount2",
          "element" : {
            "accountname":"MassCreate Test 2",
            "website":"https://corebos.org",
            "assigned_user_id":"19x5",
            "description":"mass create test",
          }
        },
        {
          "elementType" : "Accounts",
          "referenceId" : "",
          "element" : {
            "accountname":"MassCreate Test",
            "website":"https://corebos.org",
            "assigned_user_id":"19x1",
            "description":"mass create just another account with no relations",
          }
        },
        {
          "elementType" : "Products",
          "referenceId" : "",
          "element" : {
            "productname":"MassCreate Test",
            "website":"https://corebos.org",
            "assigned_user_id":"19x1",
            "description":"mass create product test",
          }
        },
    ]

and you can see some more examples in the unit tests.

MassUpsert The Mass create method can work also as a Mass Upsert method as it supports search and update functionality by means of the "searchon" parameter which you can add to any record in the composite object entries that create accepts.

The "searchon" parameter is a comma-separated list of fields you want to search on. The method will search for equality on all given fields using the values in the "elements" array. This is the exact same syntax you will find in the Upsert method below.

You can find an example in the unit tests.

MassRetrieve

MassUpdate

MassDelete

Validations. Create, Update and Revise with Validations

Besides the ValidateInformation endpoint, we also have create and update options that are identical to their base counterparts explained above just that they will validate the values before executing any operation and return the error messages without taking any action if the validations do not pass.

• CreateWithValidation Development Tool
• UpdateWithValidation
• ReviseWithValidation

Upsert

The upsert method will permit us to execute a search on some fields in a module, if we find a record that matches the search we will update it with the given values, if no record can be found we will create a new one with the given values. So it is a Search and Update or Create in one call.

Relations

coreBOS API supports defining 1:N and N:N relations between modules.

By setting a value in a foreign key (relation field or uitype 10) we establish a direct relationship between two modules.

The Create and Update operations also support a virtual meta-field named relations which contains an array of web service IDs with which we want to relate the record being created or updated. You can see an example of this here.

Finally, we have two endpoints that can establish or delete many to many relations with a large set of records: SetRelation and UnsetRelation

Metadata information

List Types

Describe

The Describe service gives us detailed information about the module which we are trying to access. It will inform us both of the types of actions permitted and all the information of the fields which we have access to.

This is extremely important as it is the only way to obtain the objectid of a module. In the introduction, we explained that each record in web service has a unique identifier composed of the module web service id and the record's crmid. The Describe service returns the module id we need to construct this unique identifier.

The object returned by this service contains:

• idPrefix - web service module ID
• isEntity - true if it is an entity, false if it is an extension
• label – label name of the module translated to the language of the connected user
• label_raw – internal label name of the module
• name – internal name of the module.
• createable – boolean value indicating if the connected user can create new records.
• updateable - boolean value indicating if the connected user can update existing records.
• deleteable - boolean value indicating if the connected user can delete existing records.
• retrieveable - boolean value indicating if the connected user can retrieve records.
• labelFields - main fields that represent the records in the module, the link fields
• filterFields - the default column fields to show when listing the records. Contains also the link fields and page size
• relatedModules - all the information of the modules related to this module
• fields - an array that contains all the accessible fields and their related information. Each field has these values:
  • name – internal field name.
  • label – label name translated
  • label_raw – internal label name
  • mandatory – a boolean value which indicates if it is mandatory on creation or not.
  • type – array with field data type information.
  • default – the default value of the field.
  • nullable – boolean value indicating if the field can be empty.
  • editable – boolean value indicating if the field can be modified.
  • uitype – UI type of the field
  • typeofdata – basic validation information
  • sequence – order of the fields in the application
  • quickcreate – boolean value indicating if the field is present in quick create or not
  • displaytype
  • summary – letter indicating if the field is present in the page header information
    • T: should appear in title
    • H: should appear in header
    • B: should appear in body
    • N: does not appear in page header
  • block – array with block information
    • blockid: internal ID of the block
    • blocksequence: order of the block
    • blocklabel: raw label of the block
    • blockname: translated label of the block

Filters/Views

User Information

Other Information

There are two deprecated endpoints that you can use to get specific information that is already available using Describe. These methods will not be eliminated, so they can be used if you need them.

Other Operations

Search Global Variable

SearchGlobalVar

Translations

Javascript Logging

The jsLog endpoint permits us to send any message from javascript to our coreBOS backend. If we activate the javascript logging section we will be able to send messages from javascript to our logs directory for tracing.

Sync

The sync service returns the complete set of changes that occurred to all records assigned to the connected user from a given date and time.

Next| Chapter 6:Working with Documents and Images.